Published October 25, 2026 | Version 0.5.0

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

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

Files

four-layer-memory-v0.5.0.zip

Files (59.6 kB)

Name Size
md5:e46e2891d3ea9114e0d3226203d01456
59.6 kB Preview Download