agent-memory
Portable, signed agent memory with a code-enforced fact lifecycle.
fg-agent-memory standardizes what a single agent remembers — its persistent experience
across sessions — as a signed, canonical file the agent owns. It is the per-agent
counterpart of agent-knowledge (what a group of agents
knows) and a sibling of agent-id, its sole runtime dependency.
The core idea
The record format IS the standard, not the engine. Engines compete on pipelines; the record format is the interop contract. Everything the library guarantees is stateable over the record format alone — no backend is load-bearing.
- A memory record is a typed, timestamped, provenance-carrying unit with a content-addressed id derived from its birth content. Lifecycle changes version the record around that stable id — a state change never renames it.
- Records and whole memory files are individually signable with an
fg-agent-idkeypair, under a domain-separated signing input that can never be replayed as an identity artifact. - The fact lifecycle is a deterministic state machine in code
(
active | transitional | superseded | archived), never a convention and never an LLM's judgment call. Records are never deleted.
The ghost-memory problem
The named failure mode this library targets: you learn X, later learn not-X, and stale X silently haunts retrieval forever. Here, a contradiction is a first-class state — both sides enter a visible transition pair and stay surfaced (marked disputed) until a human resolves the dispute. Nothing is silently overwritten.
Consolidation as code, not vibes
The differentiator versus typical LLM-rewrites-a-store memory systems:
- Superseding must name its successor and a reason.
- A contradiction produces a visible transition pair, never a silent overwrite.
- Rules carry machine-readable evidence links and get flagged when their evidence is invalidated.
- Archival is terminal; records are never deleted.
- The LLM is an operator inside the pipeline, never a free rewriter. Operators emit typed proposals validated against the lifecycle machine before any write — invalid proposals are rejected, never repaired.
The reference operators are deliberately model-free heuristics, so the entire framework runs and tests with no model and no backend.
What is standardized — and what deliberately isn't
| Standardized (the fixed core) | Left open (competes) |
|---|---|
| Record format, content addressing & signing domain | Storage engines (RecordStore port) |
| Lifecycle state machine & legality table | Search / ranking (SearchIndex, Embedder ports) |
| Proposal validation (rejected-never-repaired) | Extraction & consolidation intelligence (Operator port) |
Wire spec & golden vectors (spec/SPEC.md, spec/vectors.json) |
Salience tuning, engine-local sidecars |
Position in the stack
- agent-id — who an agent is (the only runtime dependency)
- agent-memory — what one agent remembers
- agent-knowledge — what a group of agents knows
Status
Version 0.1.0 (alpha) · wire format fg-agent-memory/0.1 · Python ≥ 3.11 ·
229 passing tests including the golden wire vectors · complete normative spec
(spec/SPEC.md, RFC-2119, 12 sections (§0 Rationale through §11 Redaction) Redaction). Where prose and code
disagree, the vectors win.
Treat it as a working reference, not a stable dependency — on-disk records and signatures are explicitly not stable across versions until a 1.0 freeze. Not on PyPI (source install only); license is proprietary — no open-source grant at this time.
→ Start with Getting started · Concepts · API reference · Examples