Four-Layer Agent Memory: a typed memory substrate for long-horizon LLM agents
Authors/Creators
Description
Four-Layer Agent Memory: a reference implementation
Project: liu bai (留白) Author: Liu Yinuo Version: v0.5.0 License: MIT Requirements: Python 3.10 or newer, no third-party dependencies (optional cryptography for Ed25519 signing)
What this is
A long-horizon language agent does not fail by forgetting facts; it fails by keeping the wrong things in context and losing the things that made it this agent for this person. This package is a small, dependency-free reference implementation of a four-layer memory substrate that treats memory as a typing problem rather than a retrieval problem:
A — conventions: how work should be done (rules, standing agreements) B — preferences: how the user wants things presented C — capabilities: what tools and workflows exist, and how to invoke them D — background: ordinary context — events, people, states, decisions
Each layer has its own destination on disk, its own lifetime and its own retrieval privilege. The agent's working context holds only a cursor and a pressure reading, so the prompt does not grow linearly with the life of the project.
Design commitments
-
Admission before writing. Every entry carries four independent axes: kind, authority (user-explicit / user-implied / observed / inferred / model-generated), evidence (quote / paraphrase / summary / inference), and lifecycle. Layer A is gated: only explicit user authority quoted verbatim may enter; an A-bound write that lacks it is diverted to a quarantine queue for human review. Layers B–D record the same metadata but are not gated. Provenance is audit metadata — it is neither truth nor authorization.
-
Watermark-driven consolidation. Consolidation is triggered by a measured context-pressure reading (normal → watch → act → forced → collapse), not by intuition; thresholds are calibrated from recorded usage samples (at least 20 recommended) rather than hard-coded.
-
Snapshot-cursor handoff. A new session resumes from an event log plus a snapshot and a cursor, not from a transcript; writes are atomic, commits are ordered, replays are idempotent.
-
Signed audit ledger. Every write, quarantine, review and revoke is appended to a hash-chained ledger that can be signed with HMAC-SHA256 or Ed25519, so exports can be verified by a third party.
-
Local first. Memory is plain files on disk; no hosted service is required, and export bundles include the quarantine queue, the ledger and the provenance watermark.
What is included
four_layer_memory/ — library: layered store, admission, consolidation, handoff, signing, audit, calibration, distillation, and a stdio MCP server.
four-layer-memory — CLI with 14 subcommands: init add consolidate status triggers plan handoff quarantine keygen calibrate revoke audit export demo.
four-layer-memory-mcp — Model Context Protocol server exposing eight tools: memory_load, memory_add, memory_consolidate, memory_status, memory_audit, memory_quarantine, memory_review, memory_handoff.
prompts/LOADING.md — the loading and writing contract a host should follow.
docs/ — architecture, threat model (ten threats with controls and residual risks), integration guide, and related work (Anthropic, MemGPT, Mem0, PROV-DM, AgentPoison, OWASP LLM01).
tests/ — 46 tests, including adversarial admission, ledger tamper detection, sign/verify round-trips, and MCP handshakes.
scripts/verify_release.py — release check: provenance watermark present, no secrets, no local paths, import sanity.
Five-minute quick start
pip install -e .
four-layer-memory --root ./memory_demo init
four-layer-memory --root ./memory_demo add A "Report results as tables before prose" --authority user-explicit --evidence quote --source "user, 2026-10-25" --source-event evt-1
four-layer-memory --root ./memory_demo add A "Prefer concise answers" --authority user-explicit --evidence paraphrase --source "user, 2026-10-25" --source-event evt-2
four-layer-memory --root ./memory_demo quarantine --list
four-layer-memory --root ./memory_demo audit
four-layer-memory --root ./memory_demo export --out ./bundle.zip
The first add succeeds: an explicit instruction quoted verbatim becomes a standing convention. The second is diverted to quarantine: the same content stated in paraphrase is not, by itself, enough to become a rule. quarantine --list shows it waiting for a human decision; audit reports structural, content, authorization and ledger checks; export packages the layers, the quarantine queue, the signed ledger and the watermark into one zip.
Scope and honest limitations
This is a specification-as-software release, not an empirical paper: it ships no benchmark results. Layer boundaries are judgment calls; calibrated thresholds are still empirical defaults; the threat model is deliberately narrow; and multi-agent concurrency is handled by file locking plus atomic replacement, not distributed consensus. A paired experiment design (periodic consolidation vs. watermark-triggered vs. passive compression) is described in the companion paper and is left to a resource-backed evaluation.
Provenance
The string "liu bai" appears in source headers, exported state files and the documentation as a provenance watermark. If you reuse this work, please keep the watermark and cite the repository via CITATION.cff.