agent-memory

Portable, auditable, cross-vendor memory for LLM agents.

Memory here is not a store of facts. It is an append-only ledger of claims, each made by an identified author (human, or an agent with a vendor lineage) and bound to evidence that can be re-run. What any agent sees is a compiled view over that ledger, and every compilation is itself recorded. So you can always answer the three questions that matter after something goes wrong: what did this agent see, what did it claim, and can the proof be re-run.

Works the same for Claude Code, Codex CLI, Antigravity (and the enterprise Gemini CLI it replaced for consumers), Cursor, Grok Build, a local Qwen on Ollama or vLLM, a CI job, and a human at a terminal. Plain files, no service, no dependencies, Python 3.10+.

The rules that make it different

• An outcome cannot be filed without a receipt. "Tests pass" must cite an ev_ receipt from running the command through agent-memory run, or a commit/file hash. The claim is rejected otherwise. A receipt is the filer's record; the proof is the re-run, which verify and the nightly lane perform, and the audit lists what nobody has re-run.
• Same-vendor review is not verification. A Claude reviewer approving a Claude coder yields self-verified. Only a human or a different vendor lineage (Codex, Gemini, a local Qwen) promotes a claim to verified.
• Refuting a claim taints everything built on it. Retractions walk the provenance graph; nothing is deleted; the audit prints the chain.
• Verifiers are isolated, workers fork. A reviewer never sees the submitter's decisions or directions; a fixer inherits the diagnosis.
• Failures are kept. Refuted outcomes and failed exemplars come back as a "do not retry" list instead of vanishing in a summary.
• Every compiled context is receipted (unless you ask it not to be with --no-receipt or receipt=false): included ids, exclusions with reasons, and the hash of the rendered text.
• A recheck that cannot ask the world is inconclusive, never a refutation. On another machine a receipt's path may not exist; with a path map it can still match, and the nightly agent-memory recheck lane files what it found under its own lineage.
• Records can be signed. Optional Ed25519 attestations (DSSE) prove who filed a line; they never change a tier.

Sixty seconds

pip install strata-agent-memory     # the CLI is `agent-memory`; or, from a checkout: pip install -e .
cd your-project && agent-memory init

agent-memory run -- pytest -q                     # -> {"id": "ev_…", "kind": "test", "passed": 42, ...}
agent-memory claim outcome "auth tests pass" -e ev_… --commit
agent-memory claim outcome "deployed" # -> rejected: outcome claims require at least one receipt

agent-memory claim fact "sessions renew via renewSession()" --source src/auth.py
agent-memory claim decision "one review lane goes to Codex" --rationale "same-vendor review cannot see its own priors"

AGENT_MEMORY_HARNESS=codex-cli agent-memory verify clm_…   # re-runs the receipt; claim becomes verified
agent-memory retract clm_… "measured on the wrong branch"  # dependents become tainted

agent-memory claim fact "w3lib.get_meta_refresh takes baseurl" --source w3lib/html.py --env uv.lock
                                                            # --env binds a lockfile that exists in your project: the fact goes
                                                            # stale when deps change, not refuted (drop --env if you have none)

agent-memory compile --role worker --task "extend auth"    # a fork-mode brief; reports what memory holds nothing on
agent-memory compile --role verifier --contract ctr_… --round 2 --lens security   # isolated review brief with a lens
agent-memory audit                                          # tiers, static-only outcomes, taint chains, verifier lineage matrix
agent-memory reliability                                    # how often claims like these were refuted, with n and an interval; fitted staleness
AGENT_MEMORY_HARNESS=ollama agent-memory recheck --map /Users/craig/src=/home/chris/src   # the nightly lane, from another machine
agent-memory serve                                          # HTTP API, SSE and remote MCP on loopback; add --tokens FILE
                                                            # (see examples/remote/curl.md) to let cloud agents in behind TLS
agent-memory keygen && agent-memory claim fact "..." --source src/x.py --sign   # optional: sign what you file
agent-memory export --format claim-evidence-map             # or prov-json, in-toto (with DSSE envelopes for signed records)

Receipts carry an assurance class (static, dynamic, adversarial) so a clean lint exit is never mistaken for a passing test suite; the audit lists outcome claims that rest on static evidence only.

Inside Claude Code, Codex or Gemini the same operations are MCP tools (memory_run, memory_claim, memory_verify, memory_compile, …); see examples/ and docs/INTEGRATION.md.

Where this goes: measured reliability, then judged claims

Memory is often perception, not fact. The alpha separates the two structurally: outcomes and file-bound facts are decided by re-running receipts; decisions, directions, preferences and exemplars are judgment and carry no verdict. The next phases add reliability signals for both, in this order, with one rule throughout: no model ever runs inside validation, and every score is either computed from records with authors or is itself a record with an author.

No statistic or judge ever promotes or demotes a claim; the one thing history recalibrates is the staleness boundary. verified keeps meaning that someone outside the author's lineage re-ran the proof. The full plan, the record shapes and text wireframes of every new surface are in docs/ROADMAP.md; the phase 3 specification with tests and acceptance is docs/PHASE3-RELIABILITY.md.

Hosting: there is no required service. Git is the database, CI or cron is the scheduler, and every clone is a backup. agent-memory serve adds a disposable replica: a SQLite index rebuilt from the shards, bearer-token identity, an HTTP API, server-sent events, a remote MCP endpoint (Streamable HTTP, revisions 2025-03-26, 2025-06-18 and the stateless 2026-07-28, chosen per request) so cloud agents reach the ledger without a clone (Claude Code on the web only through an organization-managed connector; Codex cloud unverified), and scheduled recheck and git-sync lanes. Losing the service never loses state (docs/BETA-SPEC.md section 4, examples/remote/).

This repository's own ledger

.agent-memory/ here is the ledger of building this project: decisions, contracts, receipts of the test runs, the reviews, and the first cross-lineage verifications. It is committed and public on purpose, with the maintainers' emails, machine paths and command output in it (SECURITY.md says exactly what, and why it is not rewritten). Read it with agent-memory audit from a checkout; cite a record by its id.

Layout

agent_memory/      the package (stdlib only)
  records.py       schemas, content ids, the filing rules
  ledger.py        append-only JSONL, three scopes, fsck
  evidence.py      receipts: run-and-capture, commit/file/diff bindings, re-check
  trust.py         tiers, cross-vendor rule, taint propagation, fitted staleness
  stats.py         Jeffreys/Wilson intervals, Kaplan-Meier survival (stdlib)
  reliability.py   refutation priors, same-lineage agreement, staleness fit, judgment calibration
  compiler.py      role/mode policy, ranking, budget, cross-check obligations, reliability annotations
  render.py        markdown / system / json
  contracts.py     the agreement layer
  compact.py       ancestry-preserving compaction
  memorizer.py     optional LLM extraction via any OpenAI-compatible endpoint
  mcp_server.py    stdio JSON-RPC MCP server
  serve.py         HTTP API, SSE, remote MCP (Streamable HTTP), SQLite index, scheduled lanes
  recheck.py       the nightly verifier lane as one command
  pathmap.py       answering another machine's receipts
  signing.py       optional Ed25519 attestations (DSSE); needs strata-agent-memory[sign]
  hooks.py         hook adapters: Claude Code, Codex CLI, Gemini CLI, Cursor
  cli.py           agent-memory <command>
docs/              DESIGN.md, PROTOCOL.md, RESEARCH-SYNTHESIS.md, INTEGRATION.md
schemas/           JSON Schema for the record envelope and bodies
examples/          Claude Code, Codex, Gemini, local LLM, CI
tests/             pytest suite; tests/sit/phase3/ is the CLI-driven system test

Read next

• docs/DESIGN.md: why memory is a ledger of evidence-bound claims, and which research each decision comes from.
• docs/PROTOCOL.md: the normative format, filing rules, trust computation and compile semantics, for implementers in any language.
• docs/RESEARCH-SYNTHESIS.md: the nine sources, what was taken from each, and what none of them had.
• docs/INTEGRATION.md: setup per harness, the local verifier lane, the contract loop.
• docs/LANDSCAPE.md: the competing systems, their verified licenses, the standards receipts align with, and what none of them do.
• docs/UAT-PLAN.md: the one-week acceptance test across Claude Code, Codex, Antigravity and Grok.
• docs/UAT-SELF.md: the same test for one person with two subscriptions, Claude Code and Codex CLI, with scripts/uat/ to set it up and to run the cross-lineage verification.
• docs/STATUS.md: what is built and verified, the decisions in force with their ledger ids, hosting today, and what is next.
• docs/ROADMAP.md: phases 3 to 5 (measured reliability, LLM judges as authors, learned layers), hosting, and wireframes of each new surface.
• docs/PHASE3-RELIABILITY.md: the phase 3 specification: reliability priors, fitted staleness, judgment calibration.
• docs/BETA-SPEC.md: the beta specification: cross-machine rechecks, the recheck lane, agent-memory serve with remote MCP, signing, the issue bridge, and the review fixes.
• docs/audits/: the principal-engineer reviews of the beta, the pull request and horizon 1, kept verbatim, with every finding's resolution in the spec; plus the verified facts behind the plan.
• docs/PLAN-NEXT.md: the next horizon: self-UAT across Claude Code and Codex, the 0.2.0 release, harness reach, phase 4 judges, scale, and the experiment the product exists to run.
• docs/PHASE4-JUDGES.md: the phase 4 implementation plan, judges as authors, in the order that is useful before any judge can be graded.
• docs/RELEASE-PLAN.md: what stands between the private beta and a public 0.2.0, including the decision about the committed ledger.
• docs/RELEASE.md: how a release is cut: CI, the smoke script, trusted publishing on a v* tag. SECURITY.md is the threat model and how to report; CONTRIBUTING.md is how work reaches main; CHANGELOG.md is what each version changed.

License

Apache-2.0. See LICENSE. This repository is the open core and stays that way: the managed service and the other layers that could be sold are built beside it in a separate repository, never under it (docs/ROADMAP.md section 10). "agent-memory" and "strata-agent-memory" are names of Strata Intelligence; the license grants no rights to them.