Q Agent Memory
Agent Memory's goal is to combine structured facts, temporal history, graph relationships, lexical/vector retrieval, episodic experience, and portable documents into one coherent memory, selecting the representation that helps each task instead of assuming a single database or RAG technique is universally best. The repository pairs that architectural thesis with executable runtime software and independent evaluation.
Theory · Benchmarks · Public benchmark site · Runtime · Documentation index · Canonical evidence dashboard · Governance
Important
Current status: executable governed runtime plus an active RC evidence program. Not a production 1.0 claim.
The qualified runtime posture is deliberately bounded to the single-host SQLite profile. Distributed or multi-host persistence is not established, and no substrate other than SQLiteTemporalGraph is production-qualified. RC composition remains governed by issue #410; the current work queue is docs/BACKLOG.md; the canonical benchmark view is reports/benchmarks/dashboard/current.md.
This is the product direction, not a list of shipped capabilities. Memory can be represented differently because its uses are different: exact facts need durable identity, events need historical validity, relationships benefit from graph traversal, semantic questions may benefit from vectors, and some artifacts are best kept inspectable as documents. These representations should cooperate through shared identity, provenance, scope, lifecycle, and governed recall, not become unrelated copies or independent truth authorities.
| Representation in the intended architecture | Purpose to qualify |
|---|---|
| Structured records | Exact identity and canonical state |
| Lexical and vector views | Complementary candidate discovery |
| Relations and graph views | Traceable relationship traversal |
| Episodes and temporal views | Historical applicability and currentness |
| Documents and portable files | Inspectable, portable knowledge |
All forms share governed identity, provenance and lifecycle boundaries; candidate discovery still precedes canonical admission and context assembly.
The system should use a representation only when it demonstrates value for a task, with correction, deletion, isolation and stale-projection controls across every materialized view. One canonical substrate may back multiple useful retrieval forms; conversely, additional specialized backends may be justified later. SQLite is today's qualified single-host canonical implementation, not a doctrine requiring all future memory to have one physical shape. The original product objective, composition qualification program #636, and substrate inventory respectively own intent, experiments, and maturity. Comparative superiority is a hypothesis to measure, not an existing claim.
Agent Memory includes working software, not just a memory-design proposal. The installable agent-memory-reference Python package exposes an AgentMemory facade with persistent single-host SQLite memory, governed writes and recall, scope-aware evidence admission, history and posture inspection. The runtime example below is executable from a checkout. This is a usable reference/conformance implementation in active release-candidate qualification, not a drop-in production service or certified security boundary.
| Present in the repository | Not shipped or not qualified |
|---|---|
Python runtime, SQLiteTemporalGraph persistence, governed lifecycle and public facade |
Distributed/multi-host persistence, production 1.0 security boundary, or qualified Postgres substrate |
| Lexical and optional semantic candidate retrieval, temporal fact/event semantics, bounded shared-evidence-neighbor recall, with one governed admission and a return budget | Qualified cross-store context composition, task-selective representation routing, or proven quality gains on someone else's workload |
| Typed relation persistence/traversal modules and an experimental Graphiti adapter | Complete graph reasoning/GraphRAG integrated into the qualified default public runtime |
| Canonical-state reconstruction and derived-projection controls | Qualified PostgreSQL or Markdown-backed memory profiles and distributed lifecycle closure |
| System-neutral evaluation adapters, reproducible benchmark machinery, evidence and dashboard | A universal benchmark score or same-harness comparisons with every competitor |
| Canonical doctrine, accepted/proposed ADRs and explicit architecture plans | Complete heterogeneous GraphRAG/Markdown/distributed composition as a qualified runtime |
Evaluating adoption? Compare the actual runtime with a competently indexed local-memory baseline using your own representative workload. Measure correct evidence, stale-memory behavior, exclusions/abstention, context cost, latency and integration burden. Our local benchmark measurements do not establish performance on your data. The Jarvis-scale synthetic evaluation has run a real Agent Memory arm against an indexed FTS5 control on fabricated records. Both remain weak on task correctness and abstention. This is a small development cohort with unequal persistence/governance costs, not accepted evidence of competitive adoption readiness.
Known measured quality limitation: #819 tracks excessive irrelevant recall on an external retrieval-only evaluation. High recall alone does not establish useful, selective task context. An opt-in #691 selective-context experiment improved known development cases but lost required evidence in full LongMemEval and was rejected for integration. #775 currently explores lexical versus claimed subject/relationship evidence in evaluation-only code, not the shipped runtime. Consult the current evidence dashboard and the exact issue evidence before adopting or claiming comparative performance; this README does not own benchmark scores or qualification decisions.
Long-term, #636 proposes governed composition of structured, episodic, temporal, procedural, vector and graph-derived memory. That entire composition is not shipped. The substrate inventory owns current maturity claims; only the single-host SQLite profile is qualified.
| Goal | Start | Next |
|---|---|---|
| Use the memory engine | Runtime | API contract, developer open path |
| Evaluate performance or compare systems | Benchmarks | Current dashboard, coverage, external adapters |
| Study governance or propose architecture | Theory | Architecture Index, ADRs, PAMA |
These are three operational roles, not three separately production-ready products. The operating model explains them; the five-layer project model separates architectural commons, Memory Evaluation, Gauntlet, reference runtime and future production runtime under #565. The Architecture Index routes claims. Actual capabilities, qualifications, baselines and scores remain authoritative in their respective code, contracts and evidence.
Probabilistic epistemics. Governed consequences.
Uncertainty may propose. Authority constrains.
A model, retriever, classifier, temporal signal, decay score, benchmark result, or external verifier may contribute evidence. None creates its own permission to mutate canonical memory or to enter active cognition outside the governed path. The load-bearing invariants include:
candidate retrieval != governed recall admission
ranking != truth
relevance != currentness
classifier confidence != permission
interpretation != authority
proposal != application
newer != superseding
recency != authority
benchmark score != memory authority
Every architectural lookup starts at docs/ARCHITECTURE_INDEX.md, the single catalog that assigns each architecture document one shelf and one owner and states the filing rule for new ones. docs/AGENTIC_MEMORY_SYSTEMS_CANONICAL_ARCHITECTURE.md is the underlying architectural explanation; the individual ADRs (index), the schemas, the code, and accepted evidence keep factual authority for their own claims. PAMA and docs/04-governance-and-pama.md own mutation authority. Implementation or benchmark evidence never silently promotes, supersedes, or rejects an ADR. The active policy and contract versions are owned by code, not prose: reference/agentmem_ref/runtime/temporal_order_constraints.py (POLICY_VERSION) and reference/agentmem_ref/api/contract.py (CONTRACT_VERSION). The longer invariant list in docs/64-current-governance-and-benchmark-dashboard.md is the historical #591/#594 reconciliation and reads as of that boundary.
Research briefs, explorations, and ancestry harvests are evidence and provenance, not doctrine; see docs/40-aligned-projects-and-intellectual-lineage.md and docs/SOURCE_RIGHTS_POLICY.md.
Explore the Agent Memory GitHub Pages benchmark site for an interactive evidence leaderboard, competitor coverage, and source-linked candidate runs. It is a read-only presentation, not the authority for accepted scores.
Benchmarking is a first-class repository function. The canonical current evidence view is reports/benchmarks/dashboard/current.md (machine-readable: current.json). Numbers are intentionally not copied into this README; the dashboard distinguishes current accepted evidence, previous accepted evidence and deltas, evidence classes, and non-numeric states such as not_run, blocked, unsupported, and evidence_gap. There is no universal aggregate score.
| If you want to | Go to |
|---|---|
| Understand the portfolio, evidence classes, and the rules for benchmark-driven change | BENCHMARKS.md |
| See which memory capabilities are measured, partially covered, or white space | docs/BENCHMARK_COVERAGE_ATLAS.md |
| Bring a memory system or a benchmark into the laboratory | docs/CONTRIBUTOR_ARCHITECTURE.md, then docs/GAUNTLET_EXTERNAL_CONTESTANT_QUICKSTART.md |
| Read how benchmark findings become bounded remediation and frozen replays | docs/56-benchmark-gauntlet-remediation-evidence.md, docs/72-benchmark-neutral-remediation-loop.md |
| Follow the per-metric leaderboard and evidence-freshness work | issues #779, #789, #795 |
benchmark score != truth
benchmark score != authority
retrieval quality != production readiness
blocked / not_run / evidence_gap != 0
From a checkout:
python -m pip install .Then:
from agentmem_ref import AgentMemory
with AgentMemory.open("./agent-memory-state", tenant="tenant:local") as memory:
memory.remember("memory:preferred-editor", "Preferred editor is VS Code")
recalled = memory.recall(
"preferred editor",
logical_memory_refs=("memory:preferred-editor",),
)
history = memory.history("memory:preferred-editor")
posture = memory.posture()The facade is a convenience layer over the versioned public contract (docs/44-public-api-contract.md). Convenience does not create authority: corrections, permanent deletion, and other consequential operations remain subject to governance. Read docs/47-developer-facade-and-local-open-path.md for defaults, recovery posture, and the threading contract, and docs/45-agent-memory-rc1-implementation-profile.md for the bounded RC profile.
"No single shape of memory is best for everything" is the design direction. It is not yet a qualified claim across storage technologies. The authoritative inventory is docs/43-substrate-inventory-and-maturity.md; the summary is:
| Substrate / topology | Status |
|---|---|
SQLiteTemporalGraph (sqlite_single_host_v1) |
RC-qualified single-host canonical substrate; the only production-credible profile |
InMemoryTemporalGraph |
Reference implementation; restart/checkpoint correctness proven; not a production persistence recommendation |
GraphitiSubstrate |
Experimental adapter; probe path uses a deprecated upstream driver; not qualified |
| Rust kernel | Shadow only; deterministic-primitive parity evidence under #602; Python remains the qualified runtime |
| Postgres, graph databases, Markdown/files, object stores | Not implemented as substrates; storage technologies until an Agent Memory profile earns qualification |
| Distributed / multi-host persistence | Not established; see the proposed distributed-runtime roadmap |
Current state has source-backed owners, in this order: the code-declared versions above; docs/43-substrate-inventory-and-maturity.md for what is qualified; reports/runtime/baseline-register.json for the current Runtime Baseline; docs/BACKLOG.md for the work queue and owner rulings; docs/SYSTEM_STATE.md for the revision-bound projection; and issues #410, #668, and #636 for live execution state. docs/64 and docs/66 are reconciliations at the #594 and #600-#602 boundaries respectively; they keep their original claims and are not refreshed. Two boundaries hold regardless of the evidence inside them:
- the qualified persistence claim is bounded single-host SQLite;
- production 1.0 is not claimed. RC1 is an explicit governed declaration decision.
reference/agentmem_ref/
├── core/ PAMA, receipts, evidence, verification, contextual recall
├── state/ canonical substrates, graph/state drivers, projections
├── contracts/ capability declarations, qualification, substitution
├── runtime/ governed adapter, restart, transactions, composition, CLI
├── memory/ governed memory kinds: epistemic, procedural, predictive, ...
├── api/ versioned public contract surfaces
├── crg/ Code Reality Graph / code-domain integration
├── harness/ characterization harnesses, depth probes, comparators
└── evaluation/ benchmark-neutral validation, Gauntlet, scorecard machinery
reference/ runners, benchmark adapters, tests (`reference/tests/`)
schemas/ machine-readable contracts
fixtures/ conformance and adversarial fixtures
docs/ doctrine, ADRs, product profiles, evaluation guidance, plans
reports/ frozen and normalized benchmark evidence, runtime baselines
sources/ source/provenance/right-to-reuse records
The layered package topology is enforced by reference/tests/test_package_layout.py from the table in scripts/restructure_package.py. The runtime never imports the evaluation package.
A repository claim should state whether it is doctrine, product contract, implementation, conformance evidence, benchmark evidence, field evidence, research/ancestry, or hypothesis. Those categories are not interchangeable, and promotion between them is deliberate. Agent Memory is the canonical owner of the generic memory machinery implemented here; EvolveAI, CodeGenome, COREFORGE, UOR-derived mechanisms, and other systems supply ancestry, evidence, or comparison surfaces, not permanent runtime ownership.
See GOVERNANCE.md, docs/policies/EVIDENCE_PROMOTION.md, and docs/REPOSITORY_OPERATING_MODEL.md.
docs/REPOSITORY_OPERATING_MODEL.mdCONTRIBUTING.mdGOVERNANCE.mddocs/README.mddocs/CONTRIBUTOR_ARCHITECTURE.mdfor systems and benchmarks
Material changes should identify whether they affect runtime behavior, doctrine, evaluation/evidence, contracts/schemas, documentation, or security/governance.
Agent Memory is licensed under the Apache License 2.0. See LICENSE and NOTICE.
Third-party sources, datasets, benchmark corpora, and referenced implementations retain their own licenses and attribution requirements. See docs/SOURCE_RIGHTS_POLICY.md and the source registry.
