GitLedger

Structural memory for agents and automation.

GitLedger is a Python library that turns a Git repository into a deterministic temporal memory substrate. It provides temporal queries, semantic diffs, trend extraction, anomaly detection, and narrative summaries over repository history.

Zero dependencies. Only Python 3.10+ and git on PATH.

%%{init: {'theme': 'neutral', 'themeVariables': {'edgeLabelBackground': 'transparent', 'lineColor': '#b0b0c8'}}}%%
flowchart TB
    A(["🤖 <b>Agent writes beliefs.json</b><br/>confidence_score: 0.92 → 0.71"])
    A --> B(["📦 <b>Repo</b><br/><i>write() · commit_event()</i>"])
    B --> C(["🗄️ <b>Git</b> · every version preserved"])
    B --> D(["⚡ <b>SQLite</b> · every field indexed"])
    C & D --> E(["🔍 <b>Later, you ask:</b>"])
    E --> F(["📜 <b>timeline</b> · <i>48 commits over 3 days</i>"])
    E --> G(["🔀 <b>diff</b> · <i>confidence_score: 0.92 → 0.71</i>"])
    E --> H(["📈 <b>trend</b> · <i>steady decline since Tuesday</i>"])
    E --> I(["⚠️ <b>anomalies</b> · <i>0.71 is 2.3σ below mean</i>"])

    style A fill:#f3f0ff,stroke:#9b8ec4,color:#3d3654,stroke-width:1.5px
    style B fill:#eef6ff,stroke:#6a9fd8,color:#2a4a6b,stroke-width:2px
    style C fill:#fff0f0,stroke:#d4868e,color:#5a2e33,stroke-width:1.5px
    style D fill:#fff0f0,stroke:#d4868e,color:#5a2e33,stroke-width:1.5px
    style E fill:#eefff2,stroke:#6abd7b,color:#2a5435,stroke-width:1.5px
    style F fill:#f8f8fc,stroke:#b0b0c8,color:#4a4a5e,stroke-width:1px
    style G fill:#f8f8fc,stroke:#b0b0c8,color:#4a4a5e,stroke-width:1px
    style H fill:#f8f8fc,stroke:#b0b0c8,color:#4a4a5e,stroke-width:1px
    style I fill:#f8f8fc,stroke:#b0b0c8,color:#4a4a5e,stroke-width:1px

    linkStyle default stroke:#c0c0d0,stroke-width:1px

Install

pip install gitledger

Quick Start

from gitledger import Repo

repo = Repo.init("./memory")

# Write structured artifacts
repo.write("agents/alpha/state.json", {
    "confidence_score": 0.85,
    "status": "active",
})

# Create an event commit
repo.commit_event("agent-alpha", "state_initialized",
    changed_paths=["agents/alpha/state.json"])

# Update state
repo.write("agents/alpha/state.json", {
    "confidence_score": 0.72,
    "status": "degraded",
})
repo.commit_event("agent-alpha", "state_updated",
    changed_paths=["agents/alpha/state.json"])

# Query the timeline
timeline = repo.timeline("agents/alpha/state.json")

# Semantic diffs — field-level, not line-level
diffs = repo.diff("agents/alpha/state.json",
    commit_a=timeline[0].hash,
    commit_b=timeline[-1].hash)

for d in diffs:
    print(f"{d.field}: {d.old_value} -> {d.new_value}")
# confidence_score: 0.85 -> 0.72
# status: active -> degraded

Core API

Anomaly Detection

# Detect outliers in a numeric field
anomalies = repo.anomalies("agents/alpha/state.json",
    field="confidence_score", sigma=2.0)

for a in anomalies:
    print(f"Anomaly: {a.value} (expected {a.expected_range}, severity={a.severity:.2f})")

Narrative Summaries

print(repo.narrate(path_pattern="agents/*"))

Between 2026-03-08 10:00 and 2026-03-08 14:00, 5 commits were recorded.

Most active files:
  - agents/alpha/state.json (3 changes)
  - agents/alpha/beliefs.json (1 change)

Event types:
  - state_updated (3)
  - beliefs_updated (1)

Architecture

Agent -> write artifacts -> commit -> index -> query-ready

• Storage: Git (immutable, causal, content-addressed)
• Index: SQLite sidecar at .gitledger/index.db (derived, rebuildable)
• Writes: Synchronous (artifact write + commit)
• Dependencies: None (stdlib + git CLI)

Documentation

• API Reference — Complete method signatures, parameters, return types, and examples
• User Guide — Practical walkthrough of all features with usage patterns
• Architecture — Module overview, data flow, design decisions
• Changelog — Version history and release notes

Examples

Runnable scripts in examples/:

• basic_usage.py — Write, commit, query timeline, semantic diff
• trend_and_anomalies.py — Trend extraction and z-score anomaly detection
• multi_agent.py — Multiple agents, correlation, drift, narratives
• wintermute_integration.py — Full agent coordination system with tasks, world state, and checkpoint management

Run any example:

cd gitledger
PYTHONPATH=src python examples/basic_usage.py

Memory Layer Model

GitLedger complements existing memory systems:

CI/CD

GitHub Actions workflows included:

• CI (ci.yml) — Test matrix across Python 3.10, 3.11, 3.12, 3.13
• Release (release.yml) — Publish to PyPI via trusted publishing on v* tags

# Tag a release
git tag v1.0.0
git push origin v1.0.0
# GitHub Actions publishes to PyPI automatically

Development

git clone https://github.com/nirvanatikku/gitledger.git
cd gitledger
pip install -e ".[dev]"
make test        # run tests
make coverage    # run with coverage
make build       # build sdist + wheel

License

MIT