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 problem isn't memory — it's memory without an immune system.

anneal-memory adds structural defenses at the citation layer that no other agent memory ships today. Patterns earn promotion through cited episode evidence with lexical-overlap explanation-grounding, fabricated citations get demoted, per-ID citation gaming surfaces a flag, replay attempts against stale episodes fail by construction, and the audit chain is SHA-256 hash-chained and tamper-evident. Stale patterns surface for the agent to act on; associations form through consolidation. These are narrow, structural primitives — not a complete defense against every form of memory drift. See Honest scope below for what these primitives catch and what they don't.

Four cognitive layers — episodic store, compressed continuity, Hebbian associations, affective state tracking — plus two sibling stores: prospective spores (what the agent intends to do next) and a crystallized pattern store (graduated wisdom held out of always-loaded context and recalled on cue, so a large body of proven knowledge stays effective without clogging attention). Together they implement Complementary Learning Systems — see The Memory Architecture below. Zero dependencies (Python stdlib only). Works with any agent framework.

Quick Start

pip install anneal-memory

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 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](docs/library-quickstart.md) for the full guide.

CLI

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

# Initialize
anneal-memory init --project-name MyAgent

# Record and recall
anneal-memory record "Chose PostgreSQL for ACID" --type decision
anneal-memory search "database"

# Agent-driven compression (same workflow as library and MCP)
anneal-memory prepare-wrap           # Get compression package
# Agent compresses...
anneal-memory save-continuity out.md # Save with validation

# Operator commands (things MCP can't do)
anneal-memory stats                  # Detailed analytics
anneal-memory graph --format dot     # Association graph (Graphviz)
anneal-memory diff --wraps 5         # Wrap metric progression
anneal-memory audit --since 7d       # Read audit trail
anneal-memory export --format json   # Full store export

See [examples/agent-instructions.cli.example](examples/agent-instructions.cli.example) for the agent workflow snippet.

MCP Server

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

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 / Cursor / Windsurf — mcpServers JSON (the editor's MCP settings, or a project .mcp.json):

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

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

[mcp_servers.anneal_memory]
command = "uvx"
args = ["anneal-memory", "--project-name", "MyProject", "serve"]

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

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

Then add the agent-instructions snippet — [agent-instructions.lean.example](examples/agent-instructions.lean.example) (the always-loaded baseline) or the [.full.example](examples/agent-instructions.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](#claude-code--agent-harness-adopters-skill--snippet) below for the lean/Skill/full layering.)

> Pinned install: uvx fetches the latest published version on each run. For a pinned install, pip install anneal-memory, then set "command": "anneal-memory" with "args": ["--project-name", "MyProject", "serve"] — or point command at an absolute path to the installed binary.

All Three Paths, Same Cognitive Loop

CLI and MCP are thin transport adapters over the same library — not separate implementations. Every access pattern calls the same prepare_wrap(store) and validated_save_continuity(store, text) pipeline under the hood, preserving the same workflow: record episodes during work → compress at session boundaries → load continuity at session start. The agent that records is the agent that compresses. Compression cannot be delegated — it IS the cognition.

| | Library | CLI | MCP | |---|---|---|---| | Install | pip install anneal-memory | Same | uvx anneal-memory or same | | Record | store.record(content, type) | anneal-memory record "..." --type T | record tool | | Recall | store.recall(keyword=...) | anneal-memory search "..." | recall tool | | Compress | prepare_wrap(store) → agent → validated_save_continuity(store, text) | prepare-wrap → agent → save-continuity | prepare_wrap → agent → save_continuity | | Best for | Framework integration, custom agents | Agents with shell access, operators | MCP-enabled editors |

Framework Integrations

anneal-memory works with any agent framework through the Python library. Each guide below shows where to call the four core functions — record(), recall(), prepare_wrap(), validated_save_continuity() — within the framework's lifecycle.

| Framework | Integration Point | Guide | |-----------|------------------|-------| | LangGraph / LangChain | AgentMiddleware (before/after agent + model) | [docs/integrations/langgraph.md](docs/integrations/langgraph.md) | | CrewAI | BaseEventListener (event bus) | [docs/integrations/crewai.md](docs/integrations/crewai.md) | | OpenAI Agents SDK | RunHooks (agent lifecycle) | [docs/integrations/openai-agents.md](docs/integrations/openai-agents.md) | | Anthropic Agents SDK | agent-instructions snippet + Stop hook | [docs/integrations/anthropic-agents.md](docs/integrations/anthropic-agents.md) | | Google ADK | Callbacks + custom MemoryService | [docs/integrations/google-adk.md](docs/integrations/google-adk.md) | | Pydantic AI | AbstractCapability with Hooks | [docs/integrations/pydantic-ai.md](docs/integrations/pydantic-ai.md) | | smolagents | step_callbacks dict | [docs/integrations/smolagents.md](docs/integrations/smolagents.md) | | LlamaIndex | Instrumentation BaseEventHandler | [docs/integrations/llamaindex.md](docs/integrations/llamaindex.md) | | Haystack | Custom Tracer | [docs/integrations/haystack.md](docs/integrations/haystack.md) | | CAMEL-AI | WorkforceCallback | [docs/integrations/camel-ai.md](docs/integrations/camel-ai.md) | | AutoGen / AG2 | register_hook() | [docs/integrations/autogen.md](docs/integrations/autogen.md) | | DSPy | BaseCallback | [docs/integrations/dspy.md](docs/integrations/dspy.md) |

These guides show integration patterns based on each framework's current API. The library works with any Python framework — the pattern is always the same: initialize a Store, call record() at meaningful moments, recall() before decisions, and run the wrap sequence at session end. Don't see your framework? The [library quickstart](docs/library-quickstart.md) shows the 4-function pattern that works everywhere.

Claude Code / agent-harness adopters (Skill + snippet)

Using anneal-memory inside an agent harness — Claude Code, Codex, Gemini CLI — rather than a Python framework? The Skill and snippets are repository artifacts: they live in this GitHub repo (and the source distribution), not in the pip/uvx wheel — clone the repo or download the files directly from GitHub to use them. They layer, they aren't a menu: the lean snippet is the always-loaded baseline; the Skill adds depth on demand.

• Lean snippet — the always-loaded baseline. Paste [examples/agent-instructions.lean.example](examples/agent-instructions.lean.example) (MCP) or [examples/agent-instructions.lean.cli.example](examples/agent-instructions.lean.cli.example) (CLI) into your CLAUDE.md / AGENTS.md / GEMINI.md. ~45 lines, always in context — the start-of-session continuity load, recording, recall-before-decisions, and the wrap sequence, with depth delegated to the Skill. (Copy-paste text; nothing to install.)
• The Skill — depth on demand. Copy the [skill/anneal-memory/](skill/anneal-memory) directory into .claude/skills/ (per-project) or ~/.claude/skills/ (global). [SKILL.md](skill/anneal-memory/SKILL.md) carries the comprehensive workflow and is model-invoked when you're doing memory work — primarily before decisions and on wrap. It is depth-on-demand, not a replacement for the lean snippet: a model-invoked skill won't reliably fire at a bare session start, so keep the lean snippet in place for the start-of-session step.
• The full reference — everything inline. [examples/agent-instructions.full.example](examples/agent-instructions.full.example) / [.full.cli.example](examples/agent-instructions.full.cli.example) are the complete snippets (immune-system internals, the affective-state shape, the operator-command catalog) for adopters who'd rather keep it all in their instructions file than install a Skill.

After upgrading the package, run anneal-memory migrate check — it proposes edits to your instructions so they don't silently drift from the substrate (it never edits your files), then anneal-memory migrate ack.

Why This Exists

Three independent production failures share one root cause: no quality mechanism between memory write and memory read.

Sycophancy amplification. Agents with persistent user memory profiles become 16–45% more sycophantic than memoryless baselines, depending on model (Gemini 2.5 Pro at 45%, others lower). Memory recalls what the user liked hearing, the agent learns to repeat it, and stored approval patterns compound across sessions (Jain et al., CHI 2026; measured with user memory profiles across Gemini and Llama variants).

Junk accumulation. A detailed production audit on Mem0's tracker documents a deployment that generated 10,134 memory entries over 32 days — 224 were usable. The rest were duplicates, self-referential loops, and hallucinated entries: recalled memories re-extracted as new memories in a feedback loop that no one designed but nothing prevented.

Harmful reinforcement. Clinical research documents AI systems with persistent memory scaffolding delusional content across sessions — stored context creates feedback loops between recalled memories and generated responses, with cases of documented real-world harm (Morrin et al., Lancet Psychiatry 202600396-7)).

Every existing MCP memory server stores memories and retrieves them. None of them ask: is this memory still true? Was it ever true? Is it making the agent worse?

anneal-memory asks all three:

• Is it true? Patterns must cite specific episode IDs as evidence to graduate. The server verifies the episodes exist and the explanation references the cited content via lexical overlap (≥2 meaningful words shared between the explanation and the episode body). Ungrounded citations demote.
• Is it still true? Graduated patterns whose dates fall behind the staleness threshold (default 7 days) surface in the next wrap's package as removal candidates. The agent decides whether to demote, refresh evidence, or carry forward.
• Is the citation evidence real? The library catches fabricated episode IDs (no matching episode → demote), suspicious reuse of the same episode across many patterns in one session (per-ID frequency ≥3 → flag), and bare graduations with no [evidence:] tag at all. The explanation-grounding check (≥2-word lexical overlap with episode content) raises the cost of fabricated evidence chains but is not a semantic-coherence check — see Honest scope below for what this catches and what it doesn't.

The result: memory as a living system, not a filing cabinet. Episodes accumulate fast, get compressed at session boundaries — and the compression IS the cognition, where patterns emerge and get validated. Co-cited episodes form lateral Hebbian associations, building a cognitive network through use. The continuity file stays bounded and always-loaded, getting denser rather than longer.

What Makes It Different

The agent memory ecosystem is converging on consolidation as the right approach — even Anthropic's Claude Code now runs a periodic consolidation pass over accumulated session data. This validates the direction: raw accumulation doesn't scale, and compression at session boundaries is where intelligence emerges.

But consolidation alone doesn't solve the problem. A system that consolidates faithfully and a system that consolidates sycophantically produce the same kind of output — compressed, structured, always-loaded. The difference is whether anything checks the quality of what got consolidated. That's the immune system.

Structural immune-system primitives at the citation layer

The library implements a set of structural defenses around how patterns earn graduation. They are narrow and specific — naming them honestly is part of the architecture.

Citation-validated graduation. Patterns start at 1x. To graduate to 2x or 3x, they must cite specific episode IDs as evidence. The server verifies those IDs exist in the current wrap's frozen episode snapshot — the cross-session episode set is intentionally out of scope. No matching episode IDs, no promotion.

Explanation-grounding check. For each cited episode, the expla

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: phillipclapham
• Source: phillipclapham/anneal-memory
• License: MIT

Install and usage instructions live in the source repository linked above.