agent-memory
Portable, signed agent memory with a code-enforced fact lifecycle.
fg-agent-memory (pip install fg-agent-memory) standardizes what a single agent
remembers — its persistent experience across sessions — as a signed, canonical file the
agent owns. The entry point is the two-call Memory porcelain — remember / recall —
over the full pipeline. 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 end to end 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.2.0 (alpha) · wire format fg-agent-memory/0.1 · Python ≥ 3.11 ·
byte-level constructions pinned by golden wire vectors · complete normative spec
(spec/SPEC.md, RFC-2119, §0 Rationale through §11 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. Published on
PyPI as fg-agent-memory; licensed under Apache-2.0.
→ Start with Getting started · Concepts · API reference · Examples