Skip to content

About

No description, website, or topics provided.

Resources

Code of conduct

Contributing

Security policy

Stars

15 stars

Watchers

0 watching

Forks

Latest commit

 

History

1,858 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Agent Memory: governed memory architecture for AI agents, shown with a layered memory stack, connected nodes, and a cyan inference spark.

Agent Memory official product logo

01010001 Agent Memory

Q Agent Memory

One governed memory system. Multiple purpose-fit representations.

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.

Validate Doctrine Evidence Architecture Maturity ADRs License

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.

Architecture objective: one memory, many forms

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.

What Agent Memory is today

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.

Start here

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.

Theory

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.

Benchmarks

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

Runtime

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.

Substrates and maturity

"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

Where the runtime stands

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.

Repository structure

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.

Evidence and maturity discipline

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.

Contributing

  1. docs/REPOSITORY_OPERATING_MODEL.md
  2. CONTRIBUTING.md
  3. GOVERNANCE.md
  4. docs/README.md
  5. docs/CONTRIBUTOR_ARCHITECTURE.md for systems and benchmarks

Material changes should identify whether they affect runtime behavior, doctrine, evaluation/evidence, contracts/schemas, documentation, or security/governance.

License

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.

About

No description, website, or topics provided.

Resources

Code of conduct

Contributing

Security policy

Stars

15 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages