# Anamnesis

> *"Your AI doesn't need to remember more. It needs to know what to recall, and when."*

**Anamnesis** (ἀνάμνησις) — from Plato's theory that learning is recollection. Not acquiring new knowledge, but recovering what was already known.

Anamnesis is a lightweight tool that builds a structured **belief graph** from your full Claude conversation history, then serves it through an MCP Server so Claude can query it on demand — instead of stuffing everything into the system prompt every turn.

Total cost: ~$1-2 for 500 conversations. One Python script. One JSON file. No vector database. No infra.

---

## The Problem

Every AI memory solution today — ChatGPT Memory, Claude Memory, MemGPT, RAG-based systems — is solving the wrong problem: *"How do I make the AI remember more?"*

The real problem: **"How does the AI know what to recall right now?"**

What's wrong with current approaches:

- **Blanket injection**: Every turn, dump all memories into the system prompt. You ask about Python syntax; the AI first reads your birthday and zodiac sign. Wasted tokens, polluted context.
- **Semantic retrieval (RAG)**: Find the "most similar" memory by embedding distance. But the most useful memory often isn't *similar* to the current query — it's the one that *fills a gap* in the current reasoning chain.
- **Black box**: Users can't see what the AI remembers, why it remembers it, or when it's being used.

---

## What Anamnesis Does

Three steps:

1. **Export** — Download your full Claude conversation history (Settings → Privacy → Export Data)
2. **Extract** — An LLM (DeepSeek/Qwen/local models) batch-extracts structured knowledge across 7 dimensions: beliefs, projects, preferences, decision patterns, relationships, emotional signals, knowledge graph edges. Each entry carries confidence scores, timestamps, and **source backpointers** to the original messages.
3. **Serve** — An MCP Server exposes query tools. Claude calls them during conversation, loading only what's relevant.

```mermaid
flowchart LR
    A["Conversation History\n(ZIP export)"] --> B["LLM Extraction\n(DeepSeek / Qwen)"]
    B --> C["Belief Graph\n(JSON)"]
    C --> D["MCP Server"]
    D --> E["query_beliefs"]
    D --> F["get_context_around"]
    D --> G["get_timeline"]
    D --> H["...4 more tools"]
    E --> I["Claude queries\non demand"]
    F --> I
    G --> I
    H --> I
```

---

## How It's Different

| Dimension | Current Solutions | Anamnesis |
|-----------|------------------|-----------|
| **Loading** | Inject everything every turn | On-demand query, load only what's needed |
| **Structure** | Flat text / vector embeddings | 7-dimensional structured belief graph + knowledge graph |
| **Transparency** | Black box | Fully inspectable, user-owned data |
| **Depth** | Stores conclusions | Stores conclusions + original conversation context (backpointers) |
| **Retrieval** | Semantic similarity | By dimension / keyword / relation chain / context backtracking |

### Context Backtracking — the key innovation

Every belief links back to the original conversation where it was born. You don't just know *"user is working on project X"* — you can see what they were discussing when they first mentioned X, their emotional state at the time, what triggered the idea.

Conclusions tell you **what**. The original scene tells you **how** and **why**.

No existing memory system does this.

### vs. Vector Databases

Vector DBs store embedding vectors of raw text chunks — they don't understand content, they encode semantic distance. Like scanning a book and filing it.

Anamnesis stores knowledge that an LLM has actually read and understood. Like reading a book and taking structured notes. Notes you can browse by topic, by time, by relationship.

### vs. GraphRAG (Microsoft)

GraphRAG builds knowledge graphs from documents for community summarization. It solves document understanding.

Anamnesis builds a cognitive graph from conversation history. It solves personal memory.

### vs. Mem0 (YC S24, $24M Series A)

Mem0 provides vector DB + knowledge graph infrastructure for developers. Enterprise-grade, requires setup and integration.

Anamnesis is for end users. One JSON file + one Python script. Total cost: a few dollars.

---

## MCP Tools

| Tool | When to use |
|------|-------------|
| `query_beliefs` | When you need the user's background, project status, preferences, or any personal context. Call proactively at conversation start. |
| `get_user_context` | When a topic comes up and you need the full picture — searches across all 7 dimensions. |
| `get_context_around` | When you find an interesting belief and want to see the original conversation where it emerged. The full scene around that aha moment. |
| `get_recent_state` | When you need to know what the user is currently working on, recent projects, emotional state. |
| `get_decision_pattern` | When you need to understand how the user makes decisions in a domain — their style, risk tolerance, thinking patterns. |
| `get_relationship` | When a person's name comes up and you need to know their relationship to the user. |
| `get_timeline` | When you need to understand what happened in a specific time period. |

---

## Quick Start

### Step 1: Export your Claude data

Go to [claude.ai](https://claude.ai) → Settings → Privacy → Export Data. You'll get an email with a ZIP file.

### Step 2: Install

```bash
git clone https://github.com/noogenesis-research/anamnesis.git
cd anamnesis
pip install -r requirements.txt
```

### Step 3: Configure API key

```bash
export DEEPSEEK_API_KEY=your_key_here
# Or edit config.py to use any OpenAI-compatible API
```

### Step 4: Extract belief graph

```bash
# Dry run first (no API calls)
python main.py path/to/claude_export.zip --dry-run

# Full extraction
python main.py path/to/claude_export.zip
```

Output lands in `output/belief_graph.json` and `output/conversations_index.json`.

### Step 5: Start MCP Server

**For Claude Code** (local, stdio):
```bash
# Add to ~/.mcp.json:
{
  "mcpServers": {
    "anamnesis": {
      "command": "python",
      "args": ["/path/to/anamnesis/mcp_server.py"]
    }
  }
}
```

**For Claude Desktop** (local, stdio):
```json
// Add to claude_desktop_config.json:
{
  "mcpServers": {
    "anamnesis": {
      "command": "python",
      "args": ["/path/to/anamnesis/mcp_server.py"]
    }
  }
}
```

**For Claude.ai** (remote, requires public server):
```bash
python mcp_server_remote.py --port 8765
# Then add the URL as a custom connector in Claude.ai settings
```

---

## Belief Graph Structure

```json
{
  "meta": {
    "extracted_at": "2026-04-04T12:00:00Z",
    "total_conversations": 127,
    "pipeline": "anamnesis v1"
  },
  "beliefs": [
    {
      "id": "b0001",
      "content": "User is a robotics researcher focusing on bipedal locomotion",
      "confidence": 0.95,
      "first_seen": "2025-11-03",
      "last_seen": "2026-03-28",
      "mention_count": 14,
      "source_conversations": ["conv-abc-001", "conv-abc-012"],
      "source_messages": [
        {
          "msg_index": 3,
          "role": "human",
          "timestamp": "2025-11-03T09:15:00Z",
          "conv_uuid": "conv-abc-001"
        }
      ]
    }
  ],
  "knowledge_graph": [
    {
      "id": "kg0001",
      "subject": "Domain Randomization",
      "relation": "enables",
      "object": "Sim-to-Real Transfer",
      "mention_count": 3
    }
  ],
  "timeline": [
    {
      "period": "2026-03",
      "active_projects": ["Bipedal Walker v3"],
      "key_events": ["First successful real-hardware transfer"]
    }
  ]
}
```

See [`example_belief_graph.json`](example_belief_graph.json) for a complete example with all 7 dimensions.

---

## Cost

| Scale | Extraction Cost | Time |
|-------|----------------|------|
| 100 conversations (~1M chars) | ~$0.30 | ~5 min |
| 500 conversations (~5M chars) | ~$1-2 | ~15 min |
| 1000 conversations | ~$3-4 | ~30 min |

Based on DeepSeek-chat pricing. Using local models (Qwen/Ollama) costs nothing.

---

## Privacy & Security

- **Fully local by default**: Belief graph lives on your machine. Nothing is uploaded anywhere.
- **You own your data**: All extracted knowledge belongs to you, not any platform.
- **Optional remote**: Deploy your own MCP server for Claude.ai access. Self-hosted, your infrastructure.
- **Open source**: All code is public. No hidden telemetry, no data exfiltration. Audit it yourself.

---

## Architecture

```
anamnesis/
├── main.py                  # Pipeline entry point
├── parser.py                # ZIP parsing, conversation preprocessing
├── extractor.py             # LLM extraction (DeepSeek API, async, with checkpointing)
├── merger.py                # Merge, deduplicate, build final belief graph
├── config.py                # Configuration and extraction prompt
├── mcp_server.py            # Local MCP server (stdio, for Claude Code/Desktop)
├── mcp_server_remote.py     # Remote MCP server (HTTP, for Claude.ai)
├── requirements.txt
├── example_belief_graph.json
└── output/                  # Generated data (gitignored)
    ├── belief_graph.json
    └── conversations_index.json
```

---

## Roadmap

### v1 (current) — Static belief graph + MCP Server
- [x] Conversation history parsing (Claude export format)
- [x] LLM structured extraction (7 dimensions)
- [x] Source backpointers (message-level provenance)
- [x] Async extraction with checkpointing and resume
- [x] MCP Server (7 tools)
- [x] Claude Desktop / Claude.ai / Claude Code compatible

### v2 — Incremental updates + post-processing
- [ ] Incremental extraction (process new conversations without re-running everything)
- [ ] Semantic deduplication (embedding-based clustering)
- [ ] Knowledge graph relation normalization (map to controlled vocabulary)
- [ ] Granularity filtering (remove ephemeral noise like "currently eating lunch")

### v3 — Uncertainty-driven selective retrieval
- [ ] Replace keyword matching with active retrieval based on current conversation uncertainty
- [ ] Belief staleness tracking + omission cost estimation
- [ ] Based on the SEC (Surprise-Enhanced Curiosity) framework: retrieval priority determined by *"how much would prediction error increase if this memory were absent"* rather than *"how similar is this memory to the current query"*

### v4 — Multi-platform
- [ ] ChatGPT conversation export support
- [ ] Gemini conversation export support
- [ ] Cross-platform belief graph merging

### Research directions
- **Cognitive State Tomography**: Inferring LLM internal cognitive states from CoT structural features
- **Belief graph as cognitive digital twin infrastructure**

---

## Theoretical Background

Anamnesis is inspired by the **SEC (Surprise-Enhanced Curiosity)** cognitive framework.

The core insight: current memory systems ask *"which stored observation is most similar to the current query?"* (forward association). The right question is *"if a particular memory were absent, how much would prediction error increase?"* (omission cost).

The value of memory isn't in how much you store. It's in recalling the right thing at the right moment.

**Related paper:**
> Deng, Shen, Zhang & Zhang (2026). "Attention Before Loss: Learning Observation Priority from Omission-Conditioned Prediction Error." *arXiv:2603.09476*. Accepted at ALIFE 2026.

---

## Contributing

Contributions welcome. Priority areas:

- **Platform adapters**: ChatGPT, Gemini, and other conversation export formats
- **Deduplication**: Better semantic similarity algorithms for belief merging
- **Relation normalization**: Mapping free-form knowledge graph relations to a controlled vocabulary
- **Extraction prompts**: Optimization for different languages and LLM providers
- **Local model support**: Testing and tuning with Qwen, Llama, Mistral via Ollama

---

## License

MIT

## Authors

[Noogenesis Research](https://skuldbrain.com)

- **Zhuoran Deng** (卓冉) — Architecture & Research
- **Shen Wan** (沈晚) — Theory & Review
- **Wren** — Implementation

---

> *"Odin feared losing Muninn more than Huginn — for thought without memory has no ground to stand on."*
>
> Anamnesis doesn't make AI remember more. It teaches AI to recall.