Chronicle is a local-first infrastructure platform that enables AI coding agents to share persistent engineering knowledge across sessions, branches, and tools.
Instead of every AI maintaining isolated chat history, Chronicle builds a versioned understanding of your project, allowing every agent to reason from the same source of truth.
Git tracks source code.
Chronicle tracks project understanding.
Note
Chronicle v1.0.0 has been released and tagged. The project is now in active V1 development. The documentation below describes both the current foundation and the V1 target architecture.
Overview • Problem • Features • Architecture • Quick Start • Documentation • Roadmap
Chronicle is a standalone infrastructure platform that enables AI coding agents to share persistent engineering knowledge across sessions, branches, and tools.
Instead of treating every AI conversation as isolated context, Chronicle creates a versioned understanding of a software project that evolves alongside its source code.
Rather than storing conversations, Chronicle stores structured engineering knowledge, including architecture decisions, project constraints, business rules, design rationale, dependencies, conventions, and implementation history.
Chronicle is designed to become the project's single source of truth for engineering knowledge.
Modern AI coding assistants have exceptional reasoning capabilities but poor long-term memory.
As projects grow, agents gradually lose important context:
- Architectural decisions
- Project constraints
- Coding conventions
- Business rules
- API contracts
- Previously rejected solutions
- Design rationale
This causes repeated mistakes, inconsistent implementations, duplicated discussions, and architectural drift.
Although the codebase evolves through version control, the knowledge behind those changes is often lost inside conversations.
Chronicle versions engineering knowledge in the same way Git versions source code.
As a project evolves, Chronicle observes meaningful changes and proposes knowledge snapshots that capture what was learned, why decisions were made, and how different parts of the system relate to one another.
Every connected AI agent works from the same evolving understanding of the project instead of rebuilding context from scratch.
Knowledge becomes searchable, verifiable, branch-aware, and versioned.
Chronicle versions engineering knowledge and detects when that knowledge drifts from the repository.
Chronicle can expose persistent engineering knowledge to AI coding agents through MCP, letting agents retrieve context and reason about drift.
Knowledge Brief Persistent engineering knowledge retrieved by an AI agent. |
Drift Analysis The agent identifies a contradiction between recorded knowledge and the current repository. |
Chronicle sits between AI coding agents and the project's persistent engineering knowledge.
flowchart TB
CLI["CLI"]
API["REST API"]
SDK["Python SDK"]
MCP["MCP Server"]
CORE["CHRONICLE<br/>Shared Knowledge Layer"]
MEM["Memories"]
REL["Knowledge Graph"]
OBS["Observations"]
SNAP["Snapshots"]
CONF["Confidence"]
EVID["Evidence & Provenance"]
VER["Verification"]
DRIFT["Drift Detection"]
DECAY["Memory Decay"]
SEARCH["Full-Text Search"]
DB[("SQLite<br/>+ Alembic")]
CLI --> CORE
API --> CORE
SDK --> CORE
MCP --> CORE
CORE --> MEM
CORE --> REL
CORE --> OBS
CORE --> SNAP
MEM --> CONF
MEM --> EVID
MEM --> VER
MEM --> DRIFT
MEM --> DECAY
MEM --> SEARCH
REL --> SEARCH
OBS --> VER
OBS --> SNAP
SNAP --> DRIFT
MEM --> DB
REL --> DB
OBS --> DB
SNAP --> DB
classDef interface fill:#E8EEF5,stroke:#52677A,stroke-width:1.5px,color:#17212B;
classDef core fill:#111111,stroke:#111111,stroke-width:2px,color:#FFFFFF;
classDef knowledge fill:#E8F2EC,stroke:#557765,stroke-width:1.5px,color:#17251D;
classDef intelligence fill:#F1EAF5,stroke:#765B82,stroke-width:1.5px,color:#241A29;
classDef storage fill:#F3EBDD,stroke:#806D4F,stroke-width:1.5px,color:#2B2419;
class CLI,API,SDK,MCP interface;
class CORE core;
class MEM,REL,OBS,SNAP knowledge;
class CONF,EVID,VER,DRIFT,DECAY,SEARCH intelligence;
class DB storage;
linkStyle 0,1,2,3 stroke:#52677A,stroke-width:1.7px;
linkStyle 4,5,6,7 stroke:#111111,stroke-width:2px;
linkStyle 8,9,10,11,12,13,14,15,16 stroke:#765B82,stroke-width:1.5px;
linkStyle 17,18,19,20 stroke:#806D4F,stroke-width:1.5px;
Chronicle acts as the shared knowledge layer between AI coding agents and the software project.
It continuously builds an understanding of the project while allowing every connected tool to read from and contribute to the same knowledge base.
| Feature | Description |
|---|---|
| Versioned Knowledge | Engineering knowledge evolves through immutable versions. |
| Knowledge Graph | Connects architecture, constraints, dependencies, and decisions via Relationships. |
| Evidence | Every knowledge object records why it exists. |
| Observations | Capture information before incorporating into project knowledge. |
| Snapshots | Capture project knowledge state at a point in time. |
| Branch-Aware Memory | Project knowledge follows Git branches. |
| Confidence | Track the reliability of stored knowledge. |
| Verification | Validate stored knowledge against the current project. |
| Drift Detection | Detect when implementation and stored knowledge diverge. |
| Memory Decay | Assess how fresh each memory has remained. |
| Local First | Every repository owns its own Chronicle repository. |
| Four Interfaces | CLI, REST API, Python SDK, and MCP server share the same core. |
| Feature | Description |
|---|---|
| Snapshot-Based Primary Storage | Knowledge evolves through snapshots instead of memory updates. |
Detailed documentation for every feature is available in the documentation sections below.
Every Chronicle project lives alongside its Git repository.
project/
├── .git/
└── .chronicle/
The .chronicle directory stores the project's versioned engineering knowledge, snapshots, metadata, indexes, and configuration.
Source code remains owned by Git.
Engineering knowledge is owned by Chronicle.
chronicle init
chronicle project create demo
chronicle memory create --project demo --name auth --content "API authentication uses OIDC."
chronicle search "authentication"
chronicle snapshot create --project demo
chronicle drift --project demoChronicle's documentation is organized by responsibility.
| Document | Description |
|---|---|
VISION.md |
Why Chronicle exists and its long-term vision |
PHILOSOPHY.md |
Core engineering principles and design philosophy |
DESIGN.md |
Product decisions and the locked V1 specification |
| Document | Description |
|---|---|
SYSTEM_ARCHITECTURE.md |
High-level system architecture |
OBJECT_MODEL.md |
Chronicle object model |
SNAPSHOTS.md |
Snapshot and versioning model |
STORAGE.md |
Storage architecture |
GRAPH.md |
Knowledge graph |
OBSERVATION.md |
Observation pipeline |
VERIFICATION.md |
Verification pipeline |
DRIFT_DETECTION.md |
Drift detection |
MERGE.md |
Merge strategy |
| Document | Description |
|---|---|
CLI.md |
Command-line interface |
REST.md |
REST API |
SDK.md |
Python SDK |
MCP.md |
MCP integration |
| Document | Description |
|---|---|
CORE_ENGINE.md |
Internal engine architecture |
STORAGE_ENGINE.md |
Persistence layer |
GIT_BRIDGE.md |
Git integration |
DATABASE_SCHEMA.md |
Database schema |
ROADMAP.md |
V1 implementation roadmap |
Chronicle is currently focused on delivering a stable Version 1.
See the full implementation roadmap in docs/implementation/ROADMAP.md.
Contributions, bug reports, feature discussions, and documentation improvements are welcome.
Please read CONTRIBUTING.md before opening an issue or pull request.
Chronicle is released under the MIT License.
See the LICENSE file for more information.



