# OpenChronicle

> Local-first Mac memory built from what you actually work on, served over MCP

- Category: Agents & Automation / Agent Memory
- Language: Python
- Licence: MIT
- Repository: https://github.com/Einsia/OpenChronicle
- Canonical page: https://ai-tldr.dev/tools/openchronicle/
- Updated: 2026-04-25

## In short

OpenChronicle is an open-source, local-first memory layer for any tool-capable LLM agent. It sits in the Agent Memory category of the Agents & Automation tools and is open-source, written in Python and licensed MIT. To get started: install from source.

## Overview

OpenChronicle is an open-source, local-first memory layer for any tool-capable LLM agent. It runs as a daemon on your Mac, captures structured context from what you are doing, and turns that stream into persistent Markdown memory: what you are working on, what you have decided, which tools you use, and which people, projects and organisations matter. Everything stays on the machine — Markdown files on disk with a local SQLite FTS5 index.

Its distinguishing choice is what it captures. Rather than a screenshot-and-OCR pipeline, OpenChronicle is AX-first: it reads macOS accessibility-tree events for the active app, focused element, edited text, URL and interaction state, with screenshots planned as a secondary signal. The project argues this is cheaper to process, better at capturing intent, and produces smaller memory that is easier to deduplicate and retain. Captured events are debounced and deduplicated, normalised into one-minute timeline blocks, grouped into sessions (idle 5m, app-switch 3m, max 2h), reduced into daily event files, then classified into user-, project-, tool-, topic-, person- and org- Markdown files, with history superseded rather than deleted.

It is positioned as an open alternative to OpenAI's Chronicle: MIT-licensed, model-agnostic (Ollama, LM Studio, OpenAI, Anthropic or any LiteLLM-compatible provider), inspectable, and usable by any agent that can call tools. The daemon hosts an MCP endpoint, which is the best-supported integration path today, with Claude Code, Claude Desktop, Codex, opencode and custom local agents listed. The README marks it as v0.1.0, macOS only, early alpha.

## What it does

- AX-first capture from macOS accessibility events — active app, focused element, visible text, URL — instead of screenshot-heavy OCR
- Session-aware writing: events are deduplicated, debounced and normalised into a timeline, then reduced into sessions rather than noisy per-snapshot logs
- Human-readable Markdown memory on disk, classified into user-, project-, tool-, topic-, person-, org- and daily event- files
- Local SQLite FTS5 index for search, with supersede-not-delete history
- An MCP endpoint at http://127.0.0.1:8742/mcp so any tool-calling agent can query persistent context
- Model-agnostic: works with local runtimes such as Ollama and LM Studio or any LiteLLM-compatible hosted provider

## Getting started

OpenChronicle requires macOS 13 or later and the Xcode Command Line Tools (`xcode-select --install`). It is installed from source with the bundled script.

1. Install from source

   Clone the repository and run the install script.

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

2. Run the daemon

   Start capturing in the background, or in the foreground while you watch it. The daemon can be paused and resumed at any time.

```bash
openchronicle start
openchronicle status
openchronicle pause
openchronicle resume
openchronicle stop
```

3. Inspect what it captured

   These commands run one stage of the pipeline by hand so you can see the raw capture, the timeline and the writer output.

```bash
openchronicle capture-once
openchronicle timeline tick
openchronicle timeline list
openchronicle writer run
openchronicle rebuild-index
```

4. Connect an agent over MCP

   Point an MCP client — Claude Code, Claude Desktop, Codex, opencode or your own agent — at the local endpoint the daemon hosts. See docs/mcp.md in the repository for per-client setup.

```text
http://127.0.0.1:8742/mcp
```

## When to use it

- Give a coding agent context about what you were working on yesterday without pasting it in again each session
- Keep working-context memory entirely on your own machine, in files you can open and edit, instead of a vendor's cloud
- Share one memory layer across several MCP clients so Claude Code and Codex see the same project history
- Build a custom agent on top of an inspectable memory store — Markdown for the facts, SQLite for the search

## Version history

- 2026-04-25: AI/TLDR covered OpenChronicle's launch as an MIT-licensed, local-first alternative to OpenAI Chronicle: it builds Markdown and SQLite agent memory from macOS accessibility-tree events rather than screenshots, and exposes it over MCP.