Skip to content

About

A local-first knowledge layer that gives AI coding agents persistent, structured memory across development sessions.

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Chronicle

Version Status Python License Local First

The Shared Memory Layer for AI Software Engineering

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

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.


The Problem

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.


The Solution

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 in Action

Chronicle versions engineering knowledge and detects when that knowledge drifts from the repository.

Knowledge Versioning

Knowledge Versioning

Engineering decisions and facts are recorded as memories with a full version history. As knowledge evolves, every change stays traceable.

Drift Detection

Drift Detection

Chronicle compares recorded knowledge context against the repository state and reports potentially affected knowledge.


Chronicle + MCP

Chronicle can expose persistent engineering knowledge to AI coding agents through MCP, letting agents retrieve context and reason about drift.

Knowledge Brief

Knowledge Brief

Persistent engineering knowledge retrieved by an AI agent.

Drift Analysis

Drift Analysis

The agent identifies a contradiction between recorded knowledge and the current repository.


Architecture

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;
Loading

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.


Core Features

Implemented

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.

Planned for V1

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.


Repository Layout

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.

Quick Start

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 demo

Documentation

Chronicle's documentation is organized by responsibility.

Design

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

Architecture

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

APIs

Document Description
CLI.md Command-line interface
REST.md REST API
SDK.md Python SDK
MCP.md MCP integration

Implementation

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

Roadmap

Chronicle is currently focused on delivering a stable Version 1.

See the full implementation roadmap in docs/implementation/ROADMAP.md.

Contributing

Contributions, bug reports, feature discussions, and documentation improvements are welcome.

Please read CONTRIBUTING.md before opening an issue or pull request.


License

Chronicle is released under the MIT License.

See the LICENSE file for more information.

About

A local-first knowledge layer that gives AI coding agents persistent, structured memory across development sessions.

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages