anneal-memory — Claude Code MCP server: setup and features
Two-layer local memory for AI agents without external dependencies or vector embeddings. It filters drift by verifying that abstracted patterns cite grounded episodic records.
claude mcp add anneal-memory -- uvx anneal-memoryWhat anneal-memory does
The server implements complementary learning systems using standard Python primitives. Agents first append raw actions and observations to an episodic log. A separate consolidation pass later compresses verified interactions into a permanent continuity profile alongside cue-recalled patterns. No vector database is required.
An internal validation pipeline checks every abstraction before graduation. A pattern moves up its rank only after citing real episodic records that share vocabulary with the explanation. Fabricated IDs or repetitive citations degrade its tier. The architecture also tracks prospective tasks alongside an append-only audit trail.
On Windows, advisory file locks degrade completely. Concurrent writes across distinct threads or separate processes will drop updates or race. Keeping operations strictly single-threaded avoids corruption through atomic temporary file swaps.
What it helps with
- Stop agents from accumulating ungrounded junk data across sessions
- Retain technical decisions and observations locally without vector databases
- Demote model abstractions that rely on fabricated episode citations
- Store prospective agent tasks using local Python primitives
Example prompts for the agent
- Recall earlier decisions regarding the database connection pool
- Record this architecture choice about PostgreSQL in anneal-memory
- Consolidate recent session events and update the agent continuity profile
How to install anneal-memory
Platform CLI
claude mcp add anneal-memory -- uvx anneal-memoryuvx runs the command named after the package; if the README names another one, use uvx --from anneal-memory <command>
Platform CLI
codex mcp add anneal-memory -- uvx anneal-memoryuvx runs the command named after the package; if the README names another one, use uvx --from anneal-memory <command>
Config file
{
"mcpServers": {
"anneal-memory": {
"command": "uvx",
"args": [
"anneal-memory"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from anneal-memory <command>
Config file
{
"servers": {
"anneal-memory": {
"type": "stdio",
"command": "uvx",
"args": [
"anneal-memory"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from anneal-memory <command>
Platform CLI
gemini mcp add anneal-memory uvx anneal-memoryuvx runs the command named after the package; if the README names another one, use uvx --from anneal-memory <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about anneal-memory
How to install anneal-memory in Claude Code?
Run claude mcp add anneal-memory -- uvx anneal-memory. Ensure the uv tool is installed and available in your environment.
How does the citation validation mechanism work?
Patterns must cite valid episode identifiers and share vocabulary with those records. Unverified or fabricated references drop the pattern rank to prevent hallucinations.
What are the concurrency limits on Windows?
POSIX advisory locks are unavailable on Windows, leaving files without multi-process locking. You should restrict writes to a single thread or process to prevent lost data.
