Metadata-Version: 2.4
Name: strata-agent-memory
Version: 0.2.0
Summary: Portable, auditable, cross-vendor memory for LLM agents: evidence-bound claims, trust tiers, and compiled context views.
Author: Strata Intelligence
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/thagraybush/agent-memory
Project-URL: Repository, https://github.com/thagraybush/agent-memory
Keywords: agents,memory,mcp,context-engineering,multi-agent,provenance
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: sign
Requires-Dist: cryptography>=42; extra == "sign"
Dynamic: license-file

# 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

```bash
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](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.

| phase | adds | model involved |
|---|---|---|
| 3, measured reliability (built) | refutation rates per lineage and claim type with intervals; staleness fitted from recheck history instead of a 90-day constant; borne-out rates for directions and decisions; `agent-memory reliability` | none; standard library statistics over the ledger |
| 4, model-assisted review | LLM judges as authors of `assessment` records on claims no receipt can decide; panels across lineages that surface disagreement instead of voting; judges graded against later evidence; an anchor set to catch judge drift | yes, as an author with lineage, never as the validator |
| 5, learned layers | judge aggregation weighted by measured error rates, calibrated confidence, usefulness ranking for the compiler, injection anomaly flags, contradiction candidates | optional extras; the core stays dependency-free |

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](docs/ROADMAP.md); the phase 3 specification with tests
and acceptance is [docs/PHASE3-RELIABILITY.md](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](docs/DESIGN.md): why memory is a ledger of evidence-bound claims, and which research each decision comes from.
- [docs/PROTOCOL.md](docs/PROTOCOL.md): the normative format, filing rules, trust computation and compile semantics, for implementers in any language.
- [docs/RESEARCH-SYNTHESIS.md](docs/RESEARCH-SYNTHESIS.md): the nine sources, what was taken from each, and what none of them had.
- [docs/INTEGRATION.md](docs/INTEGRATION.md): setup per harness, the local verifier lane, the contract loop.
- [docs/LANDSCAPE.md](docs/LANDSCAPE.md): the competing systems, their verified licenses, the standards receipts align with, and what none of them do.
- [docs/UAT-PLAN.md](docs/UAT-PLAN.md): the one-week acceptance test across Claude Code, Codex, Antigravity and Grok.
- [docs/UAT-SELF.md](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](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](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](docs/PHASE3-RELIABILITY.md): the phase 3 specification: reliability priors, fitted staleness, judgment calibration.
- [docs/BETA-SPEC.md](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/](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](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](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](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](docs/RELEASE.md): how a release is cut: CI, the smoke script, trusted publishing on a `v*` tag. [SECURITY.md](SECURITY.md) is the threat model and how to report; [CONTRIBUTING.md](CONTRIBUTING.md) is how work reaches main; [CHANGELOG.md](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.
