Skip to main content
Glama
lamenting-hawthorn

supermem

by lamenting-hawthorn
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

supermem

Persistent AI memory without RAG — four-tier retrieval that uses an LLM agent only as a last resort, backed by SQLite FTS5, an embedded graph database, and your local markdown vault.

PyPI Python 3.11 License: Apache 2.0 MCP Docker CI

An MCP (Model Context Protocol) server that gives AI assistants — Claude Desktop, LM Studio, ChatGPT — persistent, structured memory backed by SQLite + an optional graph database. The LLM agent is tier 4, not the default path — most queries resolve in milliseconds via full-text search.

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"]
    }
  }
}

Related MCP server: tartarus-mcp

Quick Start (Production with 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: Four-Tier Retrieval

Every query goes through tiers in order, short-circuiting when enough results are found. Tiers 1–3 never call an LLM.

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: LLM agent fallback                   ~5-30s  always available
             navigates vault via Python sandbox

Short-circuit rule: if tier 1 returns ≥ min_results (default 3), tiers 2–4 are skipped entirely. Unavailable tiers are skipped with a WARNING log — no errors raised.

MCP Tool Reference

Tool

Parameters

Returns

Notes

use_memory_agent

query: str

Formatted answer

Backward-compatible. Routes through all 4 tiers; falls back to full agent only if tiers 1–3 insufficient

supermem_hybrid

query: str, tier_limit: int = 4

JSON with obs_ids, source_tier, latency_ms

Preferred for programmatic use. Token-efficient — returns IDs first

get_observations

ids: list[int]

JSON array of observation dicts

Fetch full content for specific IDs

get_timeline

obs_id: int, window: int = 5

JSON array of chronological observations

Context around a specific observation

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)

Environment Variables

Variable

Default

Description

SUPERMEM_LLM_PROVIDER

openrouter

openrouter | ollama | claude | lmstudio

SUPERMEM_LLM_MODEL

provider default

Model string (e.g. openai/gpt-4o-mini, llama3)

SUPERMEM_DB_PATH

~/.supermem/supermem.db

SQLite database path

SUPERMEM_VAULT_PATH

.memory_path file

Markdown vault directory

SUPERMEM_VECTOR

false

Set true to enable ChromaDB tier

SUPERMEM_API_KEY

(none)

Bearer token for HTTP API auth (disabled if unset)

SUPERMEM_RATE_LIMIT

60

Requests/minute limit

SUPERMEM_WORKER_PORT

37777

HTTP dashboard port

SUPERMEM_COMPRESS_EVERY

50

Observations written before LLM compression

OPENROUTER_API_KEY

(required for openrouter)

OpenRouter API key

ANTHROPIC_API_KEY

(required for claude)

Anthropic API key

OLLAMA_HOST

http://localhost:11434

Ollama server URL

LMSTUDIO_HOST

http://localhost:1234

LM Studio server URL

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.

Endpoint

Method

Description

/health

GET

{"status":"ok","db":true,"graph":false,"vector":false}

/sessions

GET

Paginated session list with summaries

/observations

GET

Filter by session/date/type

/search

POST

{"query": "...", "tier_limit": 4}

/index/rebuild

POST

Reindex entire vault

/backup

GET

Streams vault + DB as .tar.gz

/stats

GET

{obs_count, entity_count, session_count, db_size_mb}

Auth: Authorization: Bearer <SUPERMEM_API_KEY>. Disabled when env var is unset.

Privacy

Wrap sensitive content in <private>...</private> tags. It is stripped before writing to any storage layer (SQLite, Kuzu, ChromaDB). The content passes through to the agent sandbox only — it never persists.

# Meeting Notes

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

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.

This server cannot be installed

A
license - permissive license
-
quality - not tested
A
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
1Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/lamenting-hawthorn/supermem'

If you have feedback or need assistance with the MCP directory API, please join our Discord server