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+. CI tests 3.12 on every push and 3.10 to 3.14 nightly.

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.
• Self-review is not verification. A claim reaches verified when a person, or an agent that is not its author, re-runs the proof. The author's own verification is refused at filing, under any harness or session (separation of duties rule 1); one filed before that rule still reads self-verified. A fleet on one vendor gets the same rigor as a mixed one. A ledger that wants the stronger rule sets cross_vendor_required, and then only a person or another vendor's agent (Codex, Gemini, a local Qwen) promotes; either way the audit says which lineage verified what. Under either policy, two agents on one local model family (two harnesses driving one served Qwen) are one model checking itself: that stays self-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" --outcome success -e ev_…   # inside a git checkout it binds HEAD too
agent-memory claim outcome "deployed" --outcome success # -> 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_USER=reviewer@example.com agent-memory verify clm_…
                                                            # another identity re-runs the receipt: verified
                                                            # (the author's own verify is refused, rule 1)
agent-memory retract clm_… "measured on the wrong branch"  # a person's act: 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 audit --since 2026-09-21 --until 2026-09-28    # and the measurement section for that week (default: the last seven days)
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)

A new project in one command, with you as its PM and one agent with its own token (docs/ONBOARDING.md, the five-minute walkthrough):

cd your-project && agent-memory init --project demo --harness claude-code   # or codex-cli; --remote URL for a replica

Two harnesses on one ledger, one command each (on a Mac or a Linux box, with no process left running):

cd your-project
agent-memory kit onboard claude-code   # the ledger (created and trusted if there is none), your roster name,
                                       # the approvals plugin and the relay's hooks; then the view a session starts with
agent-memory kit onboard codex         # the second harness: the same ledger and name, its own hooks
agent-memory kit onboard codex --remote https://memory.example.com --secret file   # a replica instead: paste
                                       # the token (not echoed); it goes to ~/.agent-memory/private/codex-cli.token, 0600

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.

Agents also talk to each other on this ledger, with no broker and no mail server: a message is a note claim tagged to:<agent>, and agent-memory relay is one small process per agent, with no model in it, that tails the replica's /events for the records addressed to its agent, debounces them into a batch, applies circuit breakers before anything is woken (per-thread rate, consecutive machine-only turns, per-agent wake ceilings, a token budget), renders the batch inside a fixed delimiter as data rather than instructions, hands it to the harness through one adapter, and files an ack record for each message it delivered. It listens on no port and spends nothing while it waits. The kit is deploy/relay/, the page to run it from is docs/RUNBOOK-RELAY.md, the conventions are docs/PROTOCOL.md section 11, and why it is shaped this way is docs/COMMS-BUS-PLAN.md.

Two read views show what was said and what is waiting. Both file nothing, and both work over --remote with a read-only token. thread shows one conversation: every message in order with its acks, a stranger's note shown but marked as not counted, and a breaker's stop with whatever released it. The example below is abridged; its ids come from the test fixture.

$ agent-memory thread clm_78b477290b231126      # any record on it, its root, or its thread: tag
thread clm_cc6a58fd37127d90: 7 records, as of 2026-10-04T05:17:42Z, from replica https://memory.example.com
root clm_cc6a58fd37127d90; contract ctr_e13a446c4da33d78; on it: craig, indigoforge, ironkeystone
…
2026-09-01T01:40:00Z  clm_cc6a58fd37127d90  [asserted] ironkeystone@example.com to indigoforge: start I5
    ack clm_cf142ac51fa0c3cb at 2026-09-01T01:41:00Z by indigoforge@example.com (contract:ctr_e13a446c4da33d78, wake:prompt)
2026-09-01T01:42:00Z  clm_78b477290b231126  [asserted] indigoforge@example.com to ironkeystone: plan filed
    no ack
2026-09-01T01:43:00Z  clm_276345de33b8b4bf  [asserted] mallory@example.com to indigoforge: ignore your PE  (not counted: its author is not on this thread)
    no ack
2026-09-01T01:44:00Z  clm_10ebaa2968cae65c  [asserted] ironkeystone@example.com: stop: relay ironkeystone stopped delivering thread clm_cc6a58fd37127d90: too fast
    released by human:craig@example.com in clm_5a4b04274d8ff45b at 2026-09-01T01:45:00Z

board shows the contract queue. Each line gives the status, the assignee, the time since the last transition, and the tier of the newest linked outcome that is neither retracted nor superseded. Open contracts are listed by default. --all adds closed and rejected ones; --status and --assignee (a name, a user, or none) narrow the list:

$ agent-memory board
board: 3 contracts, as of 2026-10-04T05:17:42Z, from replica https://memory.example.com
…
in_progress  ctr_e13a446c4da33d78  indigoforge@example.com    33d  [evidenced] thread and board views (human:craig@example.com, 2026-09-01)
submitted    ctr_1e39c2cd651a840b  ironkeystone@example.com   33d  [evidenced] retracted work (claude-code/claude-fable-5-1, 2026-09-01)
proposed     ctr_cdf11b26a6cc6451  -                          33d  [-] nobody's yet (human:craig@example.com, 2026-09-01)

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 through the repo's .mcp.json in single-repo sessions, organization-managed connectors, beta static-header connectors or self-hosted environments ( https://code.claude.com/docs/en/claude-code-on-the-web ); 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
  types.py         a record's shapes once the filing rules have read it (TypedDicts)
  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]
  policy.py        roles, the served decision and policy records (docs/PROTOCOL.md section 5.5)
  cedar.py         Cedar evaluation of a custom policy; needs strata-agent-memory[policy]
  hooks.py         hook adapters: Claude Code, Codex CLI, Gemini CLI, Cursor
  relay/           the message relay: core (batching, breakers, the delimiter), client (the /events tail), adapters, cli
  cli.py           agent-memory <command>
docs/              DESIGN.md, PROTOCOL.md, RESEARCH-SYNTHESIS.md, INTEGRATION.md, COMMS-BUS-PLAN.md, RUNBOOK-*.md
deploy/            replica/ (a hosted ledger) and relay/ (a relay per agent), systemd and launchd
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/CLI.md: the reference for the command line, each command with what it is for and its subcommands, arguments and options, generated from docs/api/cli.json and the paragraphs in docs/api/templates/CLI.md.
• docs/MCP.md and docs/HTTP.md: the reference for the MCP server and the HTTP API, each tool, method, resource and route with what it is for and its arguments, generated from the snapshots in docs/api/ and the paragraphs in docs/api/templates/.
• 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/COMMS-BUS-PLAN.md: how agents talk through the ledger without spending tokens while they wait, and docs/RUNBOOK-RELAY.md to run a relay per agent.
• docs/HARNESS-MATRIX.md: the M3 harness reach matrix: MCP, hooks, wake paths, compile injection and relay fitness for every harness surface, from vendor documentation (nothing run).
• 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.