Super Memory

PyPI version Python License: MIT

N:M associative memory graph for LLM agents — delivered as an MCP server.

Search "Newton" → reach "strawberry" through shared keys. Embedding similarity alone can't do this.

mcp-super-memory is an associative memory system for LLM agents built on a Key/Value graph — not a vector store. Memories live in a Value Space, accessed through a separate Key Space — one memory reachable via many keys, one key leading to many memories. This enables human-like associative leaps (multi-hop graph traversal) that pure embedding search fundamentally cannot replicate.

Works with: Claude Desktop · Claude Code · any MCP-compatible LLM agent

---

Why Not Just Embeddings?

Every existing memory system (Mem0, A-MEM, MemGPT) stores memories as nodes and retrieves them by embedding similarity. This works until it doesn't:

Query: "Newton"
Embedding search finds: "Newton discovered gravity" ✅
Embedding search misses: "user likes strawberries"   ❌

Super Memory finds both — because "Newton" → apple memory → fruit key → strawberry memory. The path exists in the key graph, not in embedding space.

---

How It Works

Key Space (concepts)         Value Space (memories)
─────────────────────        ──────────────────────────────
[Newton]  ──────────────────→ "Newton discovered gravity"
[apple]   ────────┬─────────→      ↑ same memory
[gravity] ────────┘
                  │
[apple]   ────────┼─────────→ "apples are red fruit"
[fruit]   ──────┬─┘
[red]     ──────┤
                │
[fruit]   ──────┼─────────→ "user likes strawberries"
[strawberry]────┘

Search "Newton" → matches [Newton], [apple] keys (1-hop) → follows shared [fruit] key → reaches strawberry memory (2-hop, score decayed by 0.3×).

Results include hop field — you always know if a result is direct or associative.

---

Key Features

Feature	Super Memory	A-MEM	Mem0	MemGPT
Key/Value separation	✅ N:M	❌	❌	❌
Associative multi-hop	✅ built-in	❌	❌	❌
Depth system	✅	❌	❌	partial
Memory versioning	✅ supersede	overwrites	overwrites	❌
Time decay	✅ depth-weighted	❌	❌	❌
Key types	✅ concept/name/proper_noun	❌	❌	❌
Key merge (IDF)	✅	❌	❌	❌
Dual-path recall	✅ key + content	❌	❌	❌

Depth System

Every memory has a depth score 0.0 → 1.0:

Stage	Depth	Behavior
Shallow	< 0.3	Recent, unverified. Easy to update or forget.
Medium	0.3–0.7	Confirmed multiple times. Stable.
Deep	> 0.7	Well-established fact. Resists correction.

Depth increases +0.05 each recall. Deep memories decay slower over time. If you try to correct a deep memory, it resists — its depth stays higher even after supersede.

Key Types

Not all keys should behave the same. Names shouldn't match semantically — "동건" shouldn't match "뉴턴" just because they're both short Korean words.

Type	Matching	Use Case
concept (default)	Embedding similarity ≥ 0.35	Topics, categories, attributes
name	Exact match only	Person names
proper_noun	Exact match only	Brands, places

Name/proper_noun keys also get IDF penalty (×0.5) when they become hub keys connected to many memories, preventing them from polluting unrelated searches.

Versioning (not overwriting)

"user lives in Seoul"   (depth: 0.4 → weakened to 0.12, preserved)
        ↑ superseded by
"user moved to Busan"   (depth: 0.0, new)

Unlike A-MEM which overwrites memory on evolution, Super Memory keeps the full history. Every correction is traceable — when did the belief change, and from what session?

Key Merging

Add key "파이썬"  → finds existing "Python" (similarity 0.87 > threshold 0.85)
                 → reuses existing key instead of creating duplicate

Prevents key space fragmentation. Same concept across languages or phrasing stays unified.

Dual-Path Recall

Recall searches two paths simultaneously:

• Path A (key matching): Query embedding → match keys → follow links → memories
• Path B (content matching): Query embedding → directly compare against memory content embeddings

Scores from both paths are summed. This ensures memories are found even when they weren't tagged with the right keys.

---

Architecture

┌─────────────────────────────────────────────────────────┐
│                      Key Space                          │
│   [name] [동건] [programming] [python] [fruit] [red]   │
│      ↓      ↓         ↓           ↓       ↓      ↓     │
│   [vec]  [exact]    [vec]       [vec]   [vec]  [vec]   │
└────────────────────────┬────────────────────────────────┘
                         │ N:M links
                         ↓
┌─────────────────────────────────────────────────────────┐
│                     Value Space                         │
│   "user's name is Donggeon"     depth: 0.85  (deep)    │
│   "user likes Python"           depth: 0.30  (medium)  │
│   "user likes strawberries"     depth: 0.05  (shallow) │
└─────────────────────────────────────────────────────────┘

Recall algorithm (2-hop):

1. Embed query → find matching keys (concept: similarity ≥ 0.35, name/proper_noun: exact match)
2. Also compare query embedding directly against memory content embeddings (≥ 0.3)
3. Follow links → collect memories, aggregate scores (multiple key matches sum up, IDF-weighted)
4. For each 1-hop memory: follow its keys → find 2-hop memories (score × HOP_DECAY = 0.3)
5. Apply depth factor (0.5 + depth × 0.5) and time decay (depth-weighted, 30-day half-life)
6. Return ranked results with hop field

---

MCP Tools

The memory system exposes 8 tools via MCP:

Tool	Description
recall(query, top_k)	N:M search with 2-hop associative traversal + content matching
remember(content, keys, key_types?)	Save memory with key concepts and optional type annotations
correct(memory_id, content, keys?)	Versioned update — old memory preserved but weakened
related(memory_id)	Find memories sharing keys (associative exploration)
forget(memory_id)	Permanently delete
get_conversation(session_id, turn?)	Load original conversation turns
list_memories()	List all stored memories with keys, depth, access count
memory_stats()	Get current key/memory/link counts

A system prompt template is also available via memory_system_prompt MCP prompt — include it to instruct the agent to recall silently, use diverse keys, and never mention the memory system to users.

---

Quick Start (MCP Server)

Claude Desktop

Add to claude_desktop_config.json:

OpenAI embeddings:

{
  "mcpServers": {
    "mcp-super-memory": {
      "command": "uvx",
      "args": ["mcp-super-memory"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key"
      }
    }
  }
}

Local embeddings (no API key required):

{
  "mcpServers": {
    "mcp-super-memory": {
      "command": "uvx",
      "args": ["mcp-super-memory[local]"],
      "env": {
        "EMBEDDING_BACKEND": "local"
      }
    }
  }
}

Claude Code

# OpenAI embeddings
claude mcp add mcp-super-memory -e OPENAI_API_KEY=your-openai-api-key -- uvx mcp-super-memory

# Local embeddings (no API key required)
claude mcp add mcp-super-memory -e EMBEDDING_BACKEND=local -- uvx "mcp-super-memory[local]"

Manual / Development

git clone https://github.com/donggyun112/mcp-super-memory
cd super-memory

Create .env:

OPENAI_API_KEY=your-openai-api-key
OPENAI_EMBEDDING_MODEL=text-embedding-3-small

Or use local embeddings (no API key required):

EMBEDDING_BACKEND=local
LOCAL_EMBEDDING_MODEL=paraphrase-multilingual-MiniLM-L12-v2  # optional, this is the default

Note: Mixing backends on existing data will break recall. If switching backends, clear ~/.super-memory/graph.json first.

uv sync
uv run mcp-super-memory

Requirements:

• Python 3.12+
• OpenAI API key (for embeddings) — or sentence-transformers for local embeddings

---

Data Storage

All data is local. No external database required.

data/
├── graph.json          # keys, memories, links
└── conversations/
    └── {session_id}.jsonl   # original conversation turns

---

Limitations

• Linear scan — suitable for personal use (~10k memories). FAISS/ChromaDB integration planned for larger scale.
• 2-hop max — deeper associative chains require related() tool calls by the agent.
• Agent quality matters — key selection on remember affects retrieval quality. System prompt tuning is important.

---

Comparison with A-MEM

A-MEM (NeurIPS 2025) focuses on memory evolution — when new memories arrive, existing memories' descriptions update. Super Memory focuses on memory access — how to reach the right memory through associative paths.

They solve different problems. A-MEM asks "how do we keep memories well-organized?" Super Memory asks "how do we find memories the way humans actually think?"

The versioning approach also differs: A-MEM overwrites on evolution (current state only), Super Memory preserves history (full timeline).

---

Roadmap

• FAISS/ChromaDB for scale
• Coding agent profile (different key strategies for code context)
• Memory export/import
• Multi-user support

---

License

MIT