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

... [View full README on GitHub](https://github.com/phillipclapham/anneal-memory#readme)