Skip to main content
Glama

mcp-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.


Related MCP server: Memsolus MCP Server

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

Available Tools

10 tools
cleanup_expiredA

Delete all memories past their ttl. Returns count of deleted memories. Call periodically to keep memory clean.

Inputs: no named parameters. Returns: result

correctA

Update outdated information. Use when user corrects you or info changes (e.g. moved cities, changed job). Old version is preserved but weakened — never lost. Omit keys to keep the same search terms. related_to links the updated memory to other memory IDs.

Inputs: content (required), memory_id (required), keys, key_types, +1 more. Returns: result

forgetA

Permanently delete a memory. Only use for completely wrong information. For outdated info, use correct() instead — it preserves history.

Inputs: memory_id (required). Returns: result

get_conversationA

Load raw conversation turns from a past session. Use when a recalled memory lacks detail and you need the original context.

Inputs: session_id (required), turn. Returns: result

list_memoriesA

List all stored memories. namespace filters by project/context. Expired memories are excluded. Prefer recall() for normal retrieval.

Inputs: namespace. Returns: result

memory_statsA

Get counts of keys, memories, and links in the system.

Inputs: no named parameters. Returns: result

recallA

CALL THIS FIRST before every first response. Search long-term memory by concept. namespace filters to a specific project/context. expand=True returns up to 2x results by following explicit memory links — use when initial results feel insufficient. Returns memories ranked by relevance with hop=1 (direct) or hop=2 (associative). Memories get stronger each time they're recalled.

Inputs: query (required), top_k, expand, namespace. Returns: result

rememberA

Save important information to memory. Keys are search terms — think 'what would I search to find this later?' Use 3-6 diverse keys. namespace groups memories by project/context (e.g. 'work', 'personal'). ttl_seconds sets expiry for temporary memories (e.g. 3600 = 1 hour; None = permanent). related_to links this memory to existing memory IDs for explicit graph traversal.

Inputs: keys (required), content (required), key_types, namespace, +2 more. Returns: result

remember_batchA

Save multiple memories in one call. Each item: {content, keys, key_types?, namespace?, ttl_seconds?, related_to?}. Returns list of saved IDs. More efficient than multiple remember() calls.

Inputs: items (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool has a distinct role in the memory lifecycle: creation (remember, remember_batch), retrieval (recall, list_memories, get_conversation), update (correct), deletion (forget), exploration (related), and maintenance (cleanup_expired, memory_stats). The overlap between remember and remember_batch is clearly explained as single vs batch.

    Naming Consistency5/5

    Names are consistently lowercase snake_case with clear verbs (recall, remember, correct, forget) and noun-prefixed operations (get_conversation, list_memories, memory_stats). No mixed conventions like camelCase or inconsistent verb styles.

    Tool Count5/5

    Ten tools provide comprehensive coverage without redundancy. Each tool earns its place, covering CRUD, batch operations, exploration, and system maintenance.

    Completeness4/5

    The set covers the full memory lifecycle: save, search, list, update, delete, link exploration, batch save, and maintenance. A minor gap is the lack of a direct 'get memory by ID' tool, though recall and related can surface memory content.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Provides persistent long-term memory for AI agents through semantic search and automated knowledge graph extraction. It enables agents to store, recall, and reason over facts, preferences, and relationships across multiple conversations and sessions.
      14
      17 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides persistent knowledge graph memory for AI agents, enabling them to store, recall, and query facts about people, projects, and relationships across sessions.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Associative key-graph memory for LLM agents — recall facts by association (recall → read_key → read_memory) instead of vector similarity alone, with persistent cross-session memory and cross-lingual keys.
      10
      112 npm
      3
      MIT