Anneal Memory

anneal-memory

Living memory for AI agents. Episodes compress into identity.

Memory without grounding is amplification infrastructure.

Persistent user memory profiles increase agent sycophancy 16–45% across models (Gemini 2.5 Pro at 45%, others lower). Production deployments accumulate 97.8% junk entries within weeks. Clinical research documents memory scaffolding delusions across sessions00396-7). The failure mode here isn't memory. It's memory with nothing checking what gets kept.

anneal-memory puts a check between what an agent writes down and what it comes to believe. That idea isn't rare any more. MemTxn refuses a fact update whose values don't appear in the source it cites, and Agent Zero Memory answers only from evidence its reader actually opened.

Here's what I think is actually distinct, going by the 2026 systems I've read. A pattern in anneal is an abstraction, not a copied fact, and it has to earn its rank: it moves up a level (1x → 2x → 3x, up to a 9-digit level) only when it cites real episodes its explanation is grounded in, and a failed citation drops it a level (or holds it there for a while, marked carried-forward, if it was grounded recently). The consolidator can't quietly gut the memory it rewrites, either. On a store that declares an identity layer, a save that collapses those sections is refused, and consolidators wearing down their own memory is a documented failure. Then there's the assembly. An episodic evidence store, a bounded always-loaded continuity file, a long-term pattern tier recalled on cue, prospective tasks, a single-writer consolidation gate and a hash-chained audit log all ship in one package, with zero dependencies and no embeddings. None of those pieces is unique on its own. The combination is, as far as I've found.

The citation checks are narrow and structural: cited IDs must exist, the explanation must share words with the episode it cites, fabricated citations demote (unless carryforward holds a recently grounded pattern), one episode cited too often raises a flag, and re-citing old episodes doesn't count. They are not a complete defense against memory drift. *Honest scope* below says what they catch and what they don't.

And it's memory you own and govern. A local store, zero dependencies, no vendor in the loop — you decide what graduates into long-term memory, every change is recorded in a tamper-evident chain (best-effort on the write side — see *Hash-chained audit trail* for what verify can and cannot see), and the consolidation step that rewrites an agent's identity is gated to a human, not run unbidden (the *Single-consolidator gate* below). Own the substrate; govern what enters it.

An append-only episodic log, consolidated by a single writer into a versioned identity the agent always loads, with an immune system that decides what is allowed to graduate, and a long-term pattern tier recalled on cue. Plus prospective spores (what the agent intends to do next). That's Complementary Learning Systems: a fast episodic store and slow consolidation (see *The Memory Architecture* below). Earlier versions also built a Hebbian link graph and an affect weight. I measured them for months, they never changed what recall returned, and 1.0.2 stopped building them. Zero dependencies (Python stdlib only). Works with any agent framework.

Quick Start

pip install anneal-memory

Windows

anneal-memory runs on Windows. What to know:

• Write locking is advisory POSIX `fcntl` and degrades to no lock at all on Windows. The sites (grep -n "fcntl.flock" anneal_memory/*.py) include store.py's continuity lock, crystal.py's CrystalStore._transaction, spores.py's SporeStore._transaction, and audit.py's audit manifest and audit append locks. On Windows, concurrent writers to one store — whether separate processes or threads within one process — can race or lose updates, since there is no lock of any kind to serialize them there. A single writer (one process, one thread) is unaffected: the unique-tmp + atomic-replace write still prevents a torn file.
• No fork support for the audit trail. POSIX flock locks follow the open file description, which a forked child inherits. Do not fork a process while an AuditTrail in it is in use; a child must open its own AuditTrail.
• The CLI's standard streams are UTF-8 on every platform.
• If `ANNEAL_MEMORY_DB` is unset and no home directory can be found (a launcher that drops `USERPROFILE`/`HOMEPATH`, or on POSIX a container uid with no passwd entry and no `HOME`), only a command that opens the default path needs a home, and it refuses with exit 1, naming `--db` and `ANNEAL_MEMORY_DB`.
• Windows CI runs a real but reduced subset of the suite: tests that simulate an unreadable/unlistable file or directory via POSIX chmod are skipped there, since Windows/NTFS doesn't restrict access the same way, as are the cross-process lock test (see the write-locking bullet above) and the missing-home-directory simulation that clears the whole environment (the no-home tests that patch Path.expanduser run everywhere).

Python Library

The library is the core product. Import it, use it in any framework or script.

from anneal_memory import Store, EpisodeType, prepare_wrap, validated_save_continuity

Initialize (creates DB + continuity file automatically)

store = Store("./memory.db", project_name="MyAgent")

Record episodes during work

store.record("Connection pool is the real bottleneck", EpisodeType.OBSERVATION) store.record("Chose PostgreSQL as the database because ACID outweighs speed", EpisodeType.DECISION)

Recall before decisions

result = store.recall(episode_type=EpisodeType.DECISION, keyword="database") for ep in result.episodes: print(f"[{ep.type}] {ep.content}")

Compress at session end — this is where the cognition happens

wrap = prepare_wrap(store) # fetches episodes, marks wrap in progress if wrap["status"] == "ready":

Feed wrap["package"] to your LLM. Compression IS the cognition —

patterns emerge from the act of compressing, not from storage.

compressed = your_llm.compress(wrap["package"]) validated_save_continuity(store, compressed) # full immune system pipeline

"empty" status means no new episodes to wrap — skip

store.close()

See Library Quickstart for the full guide.

CLI

Inspect, debug, and manage agent memory from the command line — a full operator CLI with machine-readable --json output. Agents with shell access (Claude Code, Aider, etc.) can use the CLI directly for the full memory workflow.

# Point the demo at its own store. Without --db or ANNEAL_MEMORY_DB every

command uses ~/.anneal-memory/memory.db, your default store.

export ANNEAL_MEMORY_DB=./demo.db

Initialize. Global flags such as --db and --project-name go before the

subcommand. --project-name names the memory in the continuity header and is

not stored: pass it on each command (the default is "Agent").

anneal-memory --project-name MyAgent init

Record and recall

anneal-memory record "Chose PostgreSQL as the database for ACID" --type decision anneal-memory search "database"

Consolidation is the operator's act: a new store wraps only under a session

you have claimed the baton for. Claim once (init --no-baton opts out).

anneal-memory baton claim me

Agent-driven compression (same workflow as library and MCP)

anneal-memory --project-name MyAgent prepare-wrap --session-id me # Get compression package

Agent compresses...

anneal-memory --project-name MyAgent save-continuity out.md \ --session-id me --wrap-token "$WRAP_TOKEN" # the 'Wrap token:' line

Operator commands (things MCP can't do)

anneal-memory stats # Detailed analytics anneal-memory graph --format dot # Graph of links formed before 1.0.2 (Graphviz) anneal-memory diff --wraps 5 # Wrap metric progression anneal-memory audit --since 7d # Read audit trail anneal-memory audit-repair # Rebuild a quarantined audit manifest, or set aside a corrupt sealed week (--set-aside-unreadable: one that only fails to read) anneal-memory export --format json # Full store export

Done with the demo: return the CLI to your default store

unset ANNEAL_MEMORY_DB

See examples/agent-instructions.lean.cli.example for the agent workflow snippet.

MCP Server

For MCP-capable agent harnesses — Claude Code, Codex and Gemini CLI.

The server is one command — anneal-memory --project-name MyProject serve — wired into the harness's MCP config. The serve subcommand starts the MCP server; --project-name (and optional --db) are global flags and come *before* serve. Each harness has its own config file and format:

Claude Code — mcpServers JSON (a project .mcp.json):

{

"mcpServers": { "anneal_memory": { "command": "uvx", "args": ["anneal-memory", "--project-name", "MyProject", "serve", "--session-id", "claude-code"] } } }

Codex — ~/.codex/config.toml (or a project .codex/config.toml):

[mcp_servers.anneal_memory]

command = "uvx" args = ["anneal-memory", "--project-name", "MyProject", "serve", "--session-id", "codex"]

Gemini CLI — ~/.gemini/settings.json (or a project .gemini/settings.json):

{

"mcpServers": { "anneal_memory": { "command": "uvx", "args": ["anneal-memory", "--project-name", "MyProject", "serve", "--session-id", "gemini"] } } }

Gemini CLI starts MCP servers only from a folder it trusts: in an untrusted folder gemini mcp list shows a server from the user-level settings as Disconnected and does not list one from a project .gemini/settings.json at all, even though the config is right (trust the folder, or set GEMINI_CLI_TRUST_WORKSPACE=true; measured with Gemini CLI 0.42.0, where the variable made the server show Connected).

Then add the agent-instructions snippet — agent-instructions.lean.example (the always-loaded baseline) or the .full.example reference — to the harness's instructions file (CLAUDE.md for Claude Code, AGENTS.md for Codex, GEMINI.md for Gemini CLI). It teaches the agent *when* and *how* to use the memory tools; without it the tools are available but the agent won't know the cognitive workflow. (See Claude Code / agent-harness adopters below for the lean/Skill/full layering.)

Consolidation is yours. Agents record episodes freely. Rewriting the agent's identity layer (the wrap) is the operator's act, so a new store consolidates only through a server whose --session-id you have claimed the baton for, once, from your own shell: uvx anneal-memory baton claim claude-code (or anneal-memory baton claim claude-code with a pip install). Until then the agent's wrap downgrades to capture-only, and both the downgrade and the status tool say how many episodes are waiting and the command for you to run. Set the id in the client's config as above, not in a shell profile (ANNEAL_MEMORY_SESSION_ID also works, but an exported one reaches every client launched from that shell). Every conversation started from one config shares its id, so after the claim each of that client's conversations may consolidate: the claim designates a client, not a single conversation. Move the baton between clients with baton claim NAME --take; see who h