Noureddine RAMDI / OpenChronicle: an AX-first local memory layer for LLM agents

Created Sat, 23 May 2026 20:41:14 +0000 Modified Sat, 23 May 2026 20:41:27 +0000
891 Words
github-stars python macos llm agent-memory async mcp

Einsia/OpenChronicle

OpenChronicle tackles a common challenge in building tool-calling large language model (LLM) agents: how to capture and store relevant context efficiently and locally for long-term memory. Instead of relying on screenshot-based OCR, which is heavy and error-prone, OpenChronicle uses macOS accessibility (AX) events to obtain structured context. This AX-first approach feeds into a multi-stage asynchronous pipeline that produces persistent Markdown memory files organized around real-world concepts like projects, topics, and daily events. It’s designed as a local-first, agent-native memory layer that integrates primarily over the MCP protocol but remains protocol-agnostic.

what openchronicle does and its architecture

OpenChronicle is an open-source memory layer built in Python, currently at early alpha (v0.1.0) and MIT-licensed. It runs on macOS 13+ and relies on the accessibility tree (AX) events emitted by macOS rather than screenshots or OCR to capture context from any tool or app. This approach reduces overhead and increases the fidelity of captured structured data.

Under the hood, OpenChronicle implements a multi-stage asynchronous pipeline:

  • Dispatcher: Listens to AX events and dispatches them for processing.
  • Parser: Converts raw AX events into structured data elements.
  • Timeline normalizer: Orders and normalizes these events into a coherent timeline.
  • Session reducer: Collapses related events into sessions representing user interactions.
  • Classifier: Categorizes events into meaningful buckets like user, project, topic, person, organization, and daily events.

The output of this pipeline is a collection of Markdown files that serve as persistent memory stores, supplemented by an SQLite FTS5 (Full-Text Search) index for efficient querying. Files are organized by entities such as user, project, tool, topic, and day.

Integration with LLM agents happens primarily through the Multi-Agent Communication Protocol (MCP) endpoint running on localhost port 8742. However, OpenChronicle’s design remains protocol-agnostic to support other agent protocols in the future.

technical strengths and design tradeoffs

What sets OpenChronicle apart is its AX-first capture mechanism. Most agent memory layers rely on screenshots or OCR to gather context, which is resource-heavy and error-prone. By tapping into the accessibility tree, OpenChronicle captures richer, structured context events asynchronously, reducing noise and improving memory quality.

The asynchronous multi-stage pipeline is another core strength, enabling scalable and modular processing of events. Each pipeline stage focuses on a specific responsibility, which aids maintainability and extensibility. For example, the classifier stage enables richer semantic organization of memory, which can improve agent reasoning.

On the flip side, this architecture also imposes tradeoffs. The dependency on macOS 13+ limits its applicability to Apple users only, leaving out Windows and Linux environments. The early alpha status means the parsers and classifiers are still rough around the edges and need community contributions to mature. The MCP integration is the only fully supported protocol currently, so adopting it with other agent protocols requires additional work.

The choice of Markdown files plus SQLite for memory storage is a pragmatic tradeoff favoring transparency and ease of inspection over more complex database solutions. This also aligns with the local-first philosophy but may have scalability limits as memory grows.

Overall, the codebase is surprisingly clean for an alpha project, with clear separation of concerns and asynchronous Python patterns. The project actively encourages community input on improving parsers, memory management, and agent integrations.

quick start

Requires macOS 13+ and Xcode Command Line Tools (xcode-select --install).

git clone https://github.com/Einsia/OpenChronicle.git
cd openchronicle
bash install.sh

This simple install process clones the repo and runs the provided install script, which sets up dependencies and builds the components. Since the project is macOS-specific and leverages system accessibility APIs, there is no cross-platform installation path yet.

The README and documentation provide examples on how to connect agents via MCP to localhost:8742 to query and update memory.

verdict

OpenChronicle offers a promising alternative to screenshot-based memory capture for tool-calling LLM agents by using macOS accessibility events. Its asynchronous pipeline and structured Markdown memory store reflect careful architectural decisions favoring transparency, extensibility, and local-first operation.

It’s still early days: the project is macOS-only, in alpha, and requires more robust parsers and agent protocol support. If you’re building tool-enabled agents on macOS and want to experiment with an open, structured local memory layer, OpenChronicle is worth a look.

For those targeting cross-platform or production-ready agent memory systems, it’s too early to adopt but worth following as it matures and the community grows.

In short, OpenChronicle solves a real problem with a technically interesting approach that deserves attention from LLM agent developers focused on local, structured memory under macOS.

→ GitHub Repo: Einsia/OpenChronicle ⭐ 2,742 · Python