MCP Memory Ledger

Local-first MCP memory for AI agents, backed by SQLite and evidence-gated self-revision.

Languages: English | Simplified Chinese | Japanese

MCP Memory Ledger is a Rust MCP stdio memory service for local AI clients. It records interactions, evidence, claims, self snapshots, and reflection audits in SQLite so an agent can use durable memory inside explicit, inspectable boundaries instead of relying only on a single prompt context.

The current project is best understood as a technical MVP for local agent memory, MCP integration, SQLite persistence, and governed self-revision. It is not a production autonomous-agent platform. Remote team mode, multi-tenancy, packaged installers, daemon write capabilities, and production security boundaries remain gated roadmap work.

Features

• Local MCP memory service: exposes ingest_interaction, build_self_snapshot, decide_with_snapshot, and run_reflection over MCP stdio.
• SQLite persistence: stores events, claims, evidence, reflection audits, trigger ledger entries, and operation logs.
• Evidence-gated self-revision: claim, identity, and commitment updates must be backed by explicit evidence and governance rules. run_reflection remains the only durable write path for identity, commitment, and reflection changes.
• Observable local diagnostics: includes a read-only dashboard, doctor preflight checks, operation-log lookup, and a redacted support-bundle generator.
• Provider integration: supports mock, openai-compatible, and OpenRouter configuration paths. Provider secrets should stay in private local config or environment variables.
• Local release gates: includes read-only checks for local alpha evidence, provider preflight, packaging preflight, and release evidence summaries. These scripts prove current boundaries; they do not publish or certify a release.

Use Cases

• Add MCP memory to a local AI client.
• Study how an agent can update long-term memory through explicit evidence.
• Validate a minimal loop for self snapshots, reflection, and commitment gates.
• Use a Rust + SQLite + MCP stdio project as an engineering reference.
• Generate local diagnostic material for provider, config, dashboard, or operation-log issues.

Quick Start

macOS:

./scripts/agent-llm-mm.sh bootstrap-local
./scripts/agent-llm-mm.sh doctor
./scripts/agent-llm-mm.sh serve

Windows:

pwsh -File .\scripts\agent-llm-mm.ps1 bootstrap-local
pwsh -File .\scripts\agent-llm-mm.ps1 doctor
pwsh -File .\scripts\agent-llm-mm.ps1 serve

bootstrap-local creates a local config template from the development example. It does not overwrite existing files, create secrets, or start the service.

Platform and integration guides:

• macOS development guide
• Windows development guide
• Local MCP integration guide

Demo

Run the reproducible self-revision demo:

./scripts/run-self-revision-demo.sh

The demo starts a deterministic local openai-compatible stub provider, runs the canonical scenario through the real MCP stdio service, and writes its report to target/reports/self-revision-demo/....

Local Diagnostics

Generate a redacted support bundle:

./scripts/generate-support-bundle.sh target/support-bundles/manual-check

The support bundle contains redacted JSON summaries only. It does not copy the full SQLite database, raw TOML, provider payloads, or raw .log files. To export a focused log excerpt or a specific MCP tool call, pass --log-file or --correlation-id explicitly.

Summarize local alpha gate evidence:

./scripts/local-alpha-evidence-summary.sh \
  --evidence-root . \
  --output-json target/reports/local-alpha/evidence-summary.json \
  --output-md target/reports/local-alpha/evidence-summary.md

This command only reads existing local evidence and writes a summary. It does not create missing evidence or certify local alpha readiness.

Current Boundaries

Implemented:

• MCP stdio main flow
• SQLite persistence with owner / namespace constraints
• Audited claim replacement through run_reflection
• Minimal identity and commitment revision
• Trigger-ledger-backed automatic self-revision MVP
• Read-only dashboard, doctor, local support bundle, and local gate summary scripts

Partially implemented:

• decide_with_snapshot still uses an action-string contract and is not a full decision engine.
• Episodes are currently lightweight projections, not a complete autobiographical memory model.
• Provider live evidence proves configuration and connectivity only. It does not prove model quality, SLA, or production readiness.
• Local alpha gates still depend on external evidence such as a real fresh-machine run, Windows parity, and a human release decision.

Not implemented:

• Full memory layering
• Richer evidence ranking / weighting
• Production-grade remote, team, or multi-tenant mode
• Daemon write capabilities and autonomous background operation
• Installers, service managers, auto-updaters, and release certification

See project status and roadmap for the complete implementation state.

Documentation

• Positioning
• FAQ
• Project overview: English
• Project overview: Simplified Chinese
• Project overview: Japanese
• Testing guide
• Release readiness
• Release gate runbook
• Local Alpha PRD
• Provider contract
• Document map

Verification

As of 2026-06-08, cargo test passes with 400 tests.

Common local checks:

cargo test
./scripts/agent-llm-mm.sh doctor
git diff --check

For provider, dashboard, release-evidence, or support-bundle changes, follow the relevant layered checks in the testing guide.

Naming

The public project name is MCP Memory Ledger. The current Rust crate, binary, scripts, config examples, and some historical docs still use agent_llm_mm / agent-llm-mm as compatibility identifiers.

Acknowledgements

This repository has been developed, reviewed, and documented with active support from OpenAI Codex as a collaborative development tool. Thanks to OpenAI for the tooling and research ecosystem that made this workflow possible.

License

This project is licensed under the Apache License 2.0. See LICENSE and NOTICE.

Copyright 2026 yooyui