Anamnesis is an ultra-lightweight working memory controller for AI agents and LLMs.
Unlike long-term memory databases or brute-force token buffers, Anamnesis models cognitive RAM: it provides real-time attention tracking, selective forgetting, and deterministic prompt pruning directly on the local execution path without consuming LLM inference tokens.
Run Anamnesis instantly via uvx (the zero-install runner for Python). If you don't have uv, install it in one command:
# macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"Add directly to your claude_desktop_config.json:
{
"mcpServers": {
"anamnesis": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/momo590/anamnesis.git",
"anamnesis-mcp"
]
}
}
}Add to your ~/.codex/config.toml:
[mcp_servers.anamnesis]
command = "uvx"
args = [
"--from",
"git+https://github.com/momo590/anamnesis.git",
"anamnesis-mcp"
]git clone https://github.com/momo590/anamnesis.git ~/.anamnesis-coreAdd to ~/.claude/settings.json:
{
"hooks": {
"UserPromptSubmit": [
{
"type": "command",
"command": "python3 ~/.anamnesis-core/integrations/claude_code_hook.py"
}
]
}
}- Go to Settings → Security & Login → Enable Developer Mode.
- Under Connectors / MCP Apps, select Add MCP Server.
- Point to your local MCP bridge (
uvx --from git+https://github.com/momo590/anamnesis.git anamnesis-mcp).
Add to your litellm_config.yaml:
litellm_settings:
callbacks: ["integrations.litellm_proxy.AnamnesisLiteLLMHandler"]Most memory frameworks for agents (Mem0, Letta/MemGPT, Zep) tackle Long-Term Memory. They act like hard drives:
- At each conversation turn, an auxiliary LLM extracts factual statements ("user prefers dark mode"), storing them into a persistent graph or vector database.
- Every retrieval relies on static semantic search or keyword matching, incurring external latency (2–4 seconds) and accumulating recurring API costs.
Meanwhile, within active agent sessions, practitioners face the limits of giant context windows:
- The "Lost-in-the-Middle" Phenomenon: As context windows swell to 100k+ tokens, model attention degrades and subtle instructions are overlooked.
- Cost and Latency: Passing massive conversation histories at every turn explodes Time-To-First-Token (TTFT) and API bills.
- The Summarization Dilemma: Recursive LLM summarization causes latency bottlenecks, doubles token overhead, and suffers from progressive information erosion.
Anamnesis operates as Cognitive RAM. Instead of storing static text cards or dumping raw chat history, it mathematically tracks continuous attention drift and prunes obsolete context in sub-millisecond local execution.
[ Incoming User/Agent Event ]
│
▼
[ Local Embedder (FastEmbed) ] ──► (384-dim vector e_t)
│
┌──────────────────────────┴──────────────────────────┐
▼ ▼
[ Micro Dialogue Anchor ] [ Macro Task Anchor ]
(alpha = 0.35, turn drift) (alpha = 0.03, intent lock)
│ │
└──────────────────────────┬──────────────────────────┘
▼
[ Dual-Head Attention Score ]
S_i = 0.6 * sim_d + 0.4 * sim_t
│
▼
[ Dynamic Context Partitioning ]
┌─────────────────────────────────┼─────────────────────────────────┐
▼ ▼ ▼
Active Tier (Pinned + I > 0.7) Warm Tier (0.3 <= I <= 0.7) Cold Tier (I < 0.3)
Verbatim injection in prompt Key-value / single-line stubs Evicted from prompt budget
-
Dual-Head Attention Anchors (
$A_t$ ):-
Micro Dialogue Anchor (
$\alpha = 0.35$ ): Glides rapidly to follow short-term conversational turns. -
Macro Task Anchor (
$\alpha = 0.03$ ): Anchors the long-term project boundaries, preventing centroid washout during digressions.$$A_{t+1} = \alpha \cdot \mathbf{e}(x_{t+1}) + (1 - \alpha) \cdot A_t$$
-
Micro Dialogue Anchor (
-
Temporal Decay & Intensity Boosts: Every memory item has an activation score
$I \in [0.0, 1.0]$ . Unused context fades smoothly turn-by-turn ($-\lambda \cdot \Delta t$ ), while active references receive immediate boosts. -
Pinned Invariants: Critical instructions (safety rules, credentials, mandatory workflows) are flagged
pinned=True. Their intensity remains locked at$1.0$ , guaranteeing permanent prompt priority immune to decay. -
Hybrid Symbolic & Vector Filtering: Antonym and negation blindspots are eliminated: deprecated or canceled orders are deterministically filtered by status, avoiding vector-similarity misfires.
-
Deterministic Zero-Token Computation: All vector updates and ranking run in under 2ms using local NumPy calculations. No LLM calls are needed to manage memory.
| Dimension | Long-Term Memory (Mem0, Letta) | Naive Context Stacking | Anamnesis Working Memory |
|---|---|---|---|
| System Role | Hard Drive (Cross-session facts) | Dumb Buffer (FIFO) | Cognitive RAM (Active focus) |
| Memory Ingestion Cost | 1 auxiliary LLM call / turn | 0 calls (token bloat) | 0 LLM calls (Local vector math) |
| Attention Management | Static semantic retrieval | None (Lost-in-the-Middle) | Dual-Head EMA drift tracking |
| Critical Constraints | Prone to dilution | Prone to truncation | Pinned slots (Guaranteed survival) |
| Turn Latency Overhead | 1000ms – 3000ms | 0ms (high TTFT upstream) | < 2ms local execution |
import numpy as np
from core.controller import AnamnesisController
# Initialize controller with 384-dimensional vector space
memory = AnamnesisController(dim=384, decay_rate=0.04)
# 1. Register an immutable pinned constraint (immune to decay)
v_rule = np.zeros(384, dtype=np.float32)
v_rule[0] = 1.0
memory.add_block(
block_id="rule_security_01",
content="CRITICAL: All database endpoints must require TLSv1.3 and mTLS.",
vector=v_rule,
pinned=True
)
# 2. Track conversational turns
v_turn = np.zeros(384, dtype=np.float32)
v_turn[0] = 0.8
memory.step_interaction(event_text="Verify ingress controller health", event_vector=v_turn)
# 3. Assemble prompt context within token budget
prompt_context = memory.assemble_prompt_context(max_tokens=600)
print(prompt_context)Run the test suite to verify centroid stability, rule survival, and symbolic exclusion:
python -m unittest tests/test_memory.py -vAll 3 assertions execute in under 2ms with zero API dependencies.
MIT License.