supermem

Persistent AI memory without RAG — local-first, lifecycle-aware retrieval backed by SQLite FTS5, an embedded graph database, and your markdown vault.

An MCP (Model Context Protocol) server for trusted local stdio clients and authenticated loopback HTTP clients. It provides persistent, structured memory backed by SQLite plus an optional graph database. Supported memory retrieval stops at lifecycle-aware tiers 1–3; raw-vault Agent navigation (Tier 4) is unavailable until a source-aware lifecycle broker exists.

Highlights

Related MCP server: tartarus-mcp

Quick Start (Personal, No GPU)

pip install supermem

# Point supermem at a directory of markdown files
export SUPERMEM_VAULT_PATH=~/notes
export SUPERMEM_LLM_PROVIDER=openrouter
export OPENROUTER_API_KEY=your_key_here

# Start the MCP server (add to Claude Desktop's mcp.json)
supermem serve

Add to Claude Desktop mcp.json:

{
  "mcpServers": {
    "supermem": {
      "command": "supermem",
      "args": ["serve"]
    }
  }
}

Quick Start (Local Docker)

# Clone and configure
git clone https://github.com/lamenting-hawthorn/supermem
cp .env.example .env
# Edit .env: set SUPERMEM_VAULT_PATH, SUPERMEM_LLM_PROVIDER, API keys

# MCP server only (stdio, for Claude Desktop)
docker compose up supermem-mcp

# MCP server + HTTP dashboard
docker compose --profile worker up

# Dashboard at http://localhost:37777

Architecture: Boundary-Aware Retrieval

Retrieval proceeds in order and short-circuits when enough results are found. Tiers 1–3 never call an LLM. Every supported transport is capped at Tier 3. Tier 4 raw-vault Agent navigation is deliberately unavailable until a source-aware lifecycle broker can enforce the same retraction and deletion policy as indexed retrieval.

Query
  │
  ├─ Tier 1: SQLite FTS5 full-text search          ~1ms    always available
  │          porter tokenizer, WAL mode
  │
  ├─ Tier 2: Kuzu embedded graph expansion         ~5ms    optional (install kuzu)
  │          BFS traversal via [[wikilink]] edges
  │
  ├─ Tier 3: ChromaDB vector similarity            ~50ms   optional (SUPERMEM_VECTOR=true)
  │          sentence-transformer embeddings
  │
  └─ Tier 4: raw-vault Agent navigation            unavailable
             pending a source-aware lifecycle broker

Short-circuit rule: if tier 1 returns ≥ min_results (default 3), tiers 2–3 are skipped entirely. Candidate IDs are filtered through observation lifecycle status before being returned, so retracted memories are excluded from search, timeline context, and derived summaries.

Memory Lifecycle and Retraction

Each observation is stored with lifecycle/provenance metadata designed for source-grounded memory:

Use retract_observation or POST /observations/{id}/retract to mark stale or sensitive records as retracted. Retraction removes the observation from FTS, filters it from hybrid retrieval, deletes vector chunks when available through the MCP/worker path, removes it from timelines and recent-session context, and invalidates derived session summaries. Retraction reasons are stored in a non-FTS audit table so the value being forgotten is not re-indexed as an active memory.

MCP Tool Reference

Progressive Disclosure Pattern

# 1. Search — cheap, returns IDs only
result = await supermem_hybrid("Alice's project status", tier_limit=2)
# {"obs_ids": [42, 17, 88], "source_tier": 1, "latency_ms": 2.1}

# 2. Fetch — only for IDs you actually need
obs = await get_observations([42, 17])
# [{"id": 42, "content": "...", "tier_used": 1}, ...]

# 3. Timeline — context around interesting observations
ctx = await get_timeline(42, window=3)

# 4. Retract — remove stale/sensitive memory from retrieval
await retract_observation(obs_id=42, reason="superseded by current roadmap")

Local Insight Pattern

# Open-loop inbox for recent memory
tasks = await list_open_tasks(days=14, limit=20)

# Turn open tasks into concise next-action prompts
followups = await suggest_followups(days=14, limit=10)

# Summarize recent days without an LLM call
summaries = await list_day_summaries(days=7)

Environment Variables

Note: Local model inference (vLLM/CUDA) is an optional extra. Install with pip install supermem[local] if you need it. Not included in the default install.

Connector Guide

Import external data into your vault with one command:

# ChatGPT export (Settings → Data controls → Export data → .zip)
supermem connect chatgpt ~/Downloads/chatgpt_export.zip

# Notion workspace export (.zip)
supermem connect notion ~/Downloads/notion_export.zip

# Nuclino workspace export (.zip)
supermem connect nuclino ~/Downloads/nuclino_export.zip

# GitHub repositories (live via API)
supermem connect github owner/repo1,owner/repo2 --token ghp_xxx

# Google Docs (OAuth, opens browser)
supermem connect google_docs "My Doc Name"

All connectors write markdown to your vault, then automatically index the files into SQLite + graph. Private content wrapped in <private>...</private> tags is stripped before indexing.

CLI Reference

supermem serve            # Start MCP server (stdio transport, for Claude Desktop)
supermem serve --worker   # Start MCP server + HTTP dashboard on :37777
supermem chat             # Interactive terminal REPL (no client required)
supermem backup           # Create timestamped .tar.gz (vault + SQLite)
supermem backup --output /path/to/archive.tar.gz
supermem restore <archive.tar.gz>
supermem connect <type> <source> [--token TOKEN] [--max-items N]

HTTP Dashboard (Optional)

Start with supermem serve --worker or docker compose --profile worker up.

Auth: protected Worker endpoints require Authorization: Bearer <SUPERMEM_API_KEY> and fail closed when the key is unset. The dashboard prompts for this key and keeps it only in the current page's JavaScript memory; it does not put the credential in the URL or browser storage, and a refresh clears it.

The primary MCP HTTP profile is authenticated, loopback-only, and stateless: each request creates no resumable MCP transport session and no MCP session ID is issued. Clients needing persistent protocol sessions should use local stdio.

Keep HTTP on a trusted loopback/private boundary. Static API-key auth does not establish remote-production or multi-tenant support; see SECURITY.md.

Privacy and Security

Wrap sensitive content in <private>...</private> tags. It is stripped before writing to any storage layer (SQLite, Kuzu, ChromaDB). Raw Agent vault content and metadata inspection are unavailable until a source-aware lifecycle broker exists. The restricted executor is not a hostile-code sandbox; remote execution remains unsupported.

# Meeting Notes

Alice discussed the roadmap.
<private>Budget: $2.4M approved for Q3</private>
Next steps: ship v2 by June.

Additional safeguards:

• Backup restore rejects archive members that would escape the configured vault.

• Notion/Nuclino ZIP imports bound member count, central-directory size, compression ratio, total extraction, parsed Markdown/CSV size, and attachment size separately.

• MCP tools share one auth/rate-limit guard and one per-client rate bucket.

• The Python executor blocks denied imports (including direct platform raw-I/O modules), scrubs inherited environment variables, and wraps common filesystem APIs; it is still a restricted local executor, not a substitute for container/OS isolation for hostile code.

• Keep current HTTP surfaces off untrusted networks. OAuth identities, scopes, installed-artifact E2E, staging, and remote-production proof remain future work; see SECURITY.md.

CI and Release Checks

Pull requests run lint, formatting, type-checking, tests with coverage, Docker build validation, and package build validation. Docker pushes and PyPI publishing remain gated to version-tag pushes (v*) so PRs validate release artifacts without publishing them.

Running Tests

uv run pytest tests/ -v                          # all tests
uv run pytest tests/unit/ -v                     # unit only (fast, no network)
uv run pytest tests/integration/ -v              # integration (real storage)
uv run pytest tests/ --cov=supermem --cov-report=term-missing  # with coverage

Coverage gate: 60% (CI enforced). Kuzu and Anthropic tests are auto-skipped if packages are not installed.

License

Apache 2.0 — see LICENSE.