gitledger 1.0.0

Structural memory for agents and automation

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

Method	Description
timeline(path, since, until)	Commit history for a path
diff(path, commit_a, commit_b)	Semantic field-level diffs
trend(path, field, since, until)	Numeric field trends
episodes(pattern, event_type, window)	Group related commits
snapshot(commit)	All file contents at a commit
drift(path, schema)	Detect field value changes
narrate(pattern, since, until)	Human-readable narrative
anomalies(path, field, sigma)	Statistical outlier detection
search(query, paths)	Search commit messages
correlate(path_a, path_b, window)	Find co-changing paths
most_changed(pattern, limit)	Most frequently modified paths

Write Method	Description
write(path, content)	Write a JSON or text artifact
commit_event(entity, event_type)	Create an event commit
commit_checkpoint(tag)	Create a checkpoint with tag
sync()	Index un-indexed commits
rebuild_index()	Rebuild the SQLite index

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:

Memory Layer	Purpose	Technology
Working Memory	Current state	Database
Episodic Memory	Recent events	Event tables
Semantic Memory	Learned knowledge	Engram systems
Vector Memory	Semantic retrieval	Vector databases
Structural Memory	State evolution	GitLedger

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