# anneal-memory

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.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 12
- Author: phillipclapham
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/phillipclapham/anneal-memory
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/mcp/anneal-memory

## What it 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.

## Requirements
- Needs: Python and uv (commands run via uvx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add anneal-memory -- uvx anneal-memory
```
uvx runs the command named after the package; if the README names another one, use uvx --from anneal-memory <command>

### Codex

**Platform CLI**
```bash
codex mcp add anneal-memory -- uvx anneal-memory
```
uvx runs the command named after the package; if the README names another one, use uvx --from anneal-memory <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add anneal-memory uvx anneal-memory
```
uvx runs the command named after the package; if the README names another one, use uvx --from anneal-memory <command>

## When to use it
- 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
- 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

## Similar
- [deep-agents-memory](https://affpapa.org/en/nevibecode/skills/deep-agents-memory.md) — skill · 19000 installs
- [agent-memory-systems](https://affpapa.org/en/nevibecode/skills/sickn33-agent-memory-systems.md) — skill · 2000 installs
- [memory-lancedb-pro-openclaw](https://affpapa.org/en/nevibecode/skills/memory-lancedb-pro-openclaw.md) — skill · 1300 installs
- [AgentDB Memory Patterns](https://affpapa.org/en/nevibecode/skills/agentdb-memory-patterns.md) — skill · 1100 installs
- [memory-search](https://affpapa.org/en/nevibecode/skills/ruvnet-memory-search.md) — skill · 750 installs
- [memory-systems](https://affpapa.org/en/nevibecode/skills/memory-systems.md) — skill · 393 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md