OpenChronicle

OpenChronicle

Open-source, memoria local-first per qualsiasi agente LLM "tool-capable".

Pensa ad OpenAI Chronicle - ma aperto, agnostico al modello, ispezionabile e hackable.

Stato: v0.1.0 · Solo macOS · alpha iniziale

OpenChronicle fornisce agli agenti AI una memoria locale e ispezionabile costruita a partire dal contesto reale dello schermo e delle applicazioni.

Funziona sul tuo Mac, cattura il contesto strutturato di ciò che stai facendo e lo trasforma in una memoria Markdown persistente: su cosa stai lavorando, cosa hai deciso, quali strumenti usi e quali persone o progetti contano.

Qualsiasi agente in grado di chiamare strumenti può usarlo. I client MCP funzionano particolarmente bene oggi, ma OpenChronicle è pensato per essere uno strato di memoria generale per agenti che usano strumenti - non qualcosa legato a un protocollo, un fornitore di modelli o un'app.

Perché OpenChronicle

OpenAI Chronicle indica un futuro importante: agenti che ricordano il tuo contesto di lavoro reale.

OpenChronicle è la nostra alternativa aperta:

• Local-first - la memoria rimane sulla tua macchina
• Model-agnostic - usa Ollama, LM Studio, OpenAI, Anthropic o qualsiasi provider compatibile con LiteLLM
• Tool-friendly - utilizzabile da qualsiasi agente in grado di usare strumenti
• Inspectable - Markdown su disco, SQLite localmente
• Open - licenza MIT e costruito per essere esteso

Perché AX-first

OpenChronicle attualmente privilegia il contesto dell'AX Tree / albero di accessibilità come segnale primario, con gli screenshot come segnale secondario nel tempo.

Crediamo che questo sia il giusto compromesso per un sistema di memoria iniziale:

• Costo inferiore - il testo strutturato è molto più economico da elaborare rispetto alle pipeline OCR / di visione pesanti sugli screenshot
• Migliore cattura dell'intento - AX è spesso migliore per l'app attiva, l'elemento focalizzato, il testo modificato, l'URL e lo stato di interazione
• Memoria più piccola e pulita - più facile da deduplicare, normalizzare, indicizzare e conservare a lungo termine
• Migliore base - gli screenshot possono in seguito arricchire il contesto visivo dove AX non riesce

AX-first per una memoria accurata, compatta e a basso costo; assistita da screenshot per un contesto multimodale più ricco.

OpenChronicle vs OpenAI Chronicle

Come funziona

flowchart LR
    W[mac-ax-watcher<br/>eventi]
    S0["<b>S0</b> dispatcher<br/>deduplicazione · debounce<br/>min-gap"]
    S1["<b>S1</b> parser<br/>focused_element<br/>visible_text · url"]
    BUF[(capture-buffer<br/>/*.json)]
    TL["Timeline<br/>normalizzatore<br/>1-min · verbatim"]
    TB[(timeline_blocks)]
    SM["Session mgr<br/>idle 5m · app-switch 3m<br/>max 2h"]
    S2["<b>S2</b> reducer"]
    ED[(event-<br/>YYYY-MM-DD.md)]
    CLF["Classifier<br/>→ user- / project- / tool- /<br/>topic- / person- / org-*.md"]
    STORE[("SQLite FTS5<br/>+ Markdown")]

    W --> S0 --> S1 --> BUF --> TL --> TB --> S2 --> ED --> CLF --> STORE
    ED --> STORE
    BUF -. pre_capture_hook<br/>(post-write · saltato su deduplicazione contenuti) .-> SM
    SM -. flush 5m / on_end .-> S2
    TB -. grounding .-> CLF

L'idea centrale è semplice:

1. catturare il contesto
2. comprimerlo in sessioni
3. estrarre fatti duraturi
4. archiviare la memoria localmente
5. permettere agli agenti di interrogarla tramite strumenti

Cosa ottieni

• Cattura guidata dagli eventi dagli eventi AX di macOS
• Scrittura della memoria consapevole delle sessioni invece di log rumorosi per ogni snapshot
• Memoria Markdown leggibile dall'uomo
• Indicizzazione SQLite locale
• File di memoria strutturati come user-, project-, tool-, topic-, person-, org- e daily event-
• Cronologia che "supersedes-not-delete" (sostituisce non cancella)
• Supporto per modelli locali o cloud
• Interfaccia sempre attiva e leggibile dall'agente, con MCP come il percorso meglio supportato oggi

Installazione

Richiede macOS 13+ e Xcode Command Line Tools (xcode-select --install).

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

Esecuzione

openchronicle start
openchronicle start --foreground
openchronicle status
openchronicle pause
openchronicle resume
openchronicle stop

Comandi utili per l'ispezione:

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

Connetti un agente

OpenChronicle è progettato per agenti che chiamano strumenti.

Percorso più supportato oggi: MCP

Il demone ospita un endpoint MCP all'indirizzo:

http://127.0.0.1:8742/mcp

I percorsi di integrazione supportati includono:

• Claude Code
• Claude Desktop
• Codex
• Opencode
• Agenti locali personalizzati
• e altro ancora...

Per i dettagli sulla configurazione, consulta docs/mcp.md.

Contribuire

Cerchiamo aiuto in particolare in tre aree:

1. Migliori parser di contesto

Parsing e normalizzazione specifici per app per browser, terminali, editor, Slack, Notion, Cursor, Linear, Figma e altro ancora.

2. Migliore gestione della memoria

Riduzione delle sessioni, estrazione di fatti duraturi, compattazione, logica di "supersede / merge" e qualità del recupero.

3. Più integrazioni con gli agenti

Supporto per più client MCP, agenti IDE, assistenti di codifica, agenti desktop e framework di orchestrazione locali.

Se ti interessano gli agenti local-first, la memoria AI personale o l'infrastruttura di contesto aperta, questo progetto fa per te.

Documentazione

• docs/architecture.md - pipeline end-to-end e layout del codice
• docs/config.md - configurazione e setup del modello
• docs/capture.md - cattura guidata dagli eventi e dettagli AX
• docs/timeline.md - normalizzazione e design anti-allucinazione
• docs/session.md - regole di "session cutting"
• docs/writer.md - reducer, classifier e modello di retry
• docs/mcp.md - interfaccia tool attuale e integrazioni
• docs/memory-format.md - layout dei file e semantica di "supersede"
• docs/troubleshooting.md - problemi comuni

Sviluppo

uv sync --all-extras
uv run pytest
uv run ruff check

Licenza

MIT.