supermem v0.1.0 — Initial Release

supermem v0.1.0 — Initial Release

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.

What is supermem?

supermem is an MCP (Model Context Protocol) server that gives AI assistants — Claude Desktop, LM Studio, ChatGPT — persistent, structured memory backed entirely on your local machine. Most queries resolve in milliseconds via full-text search; the LLM agent is a last resort, not the default path.

---

Installation

pip install recall

Quick Start (Personal, No GPU)

export RECALL_VAULT_PATH=~/notes
export RECALL_LLM_PROVIDER=openrouter
export OPENROUTER_API_KEY=your_key_here

recall serve

Add to Claude Desktop mcp.json:

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

Quick Start (Docker)

git clone https://github.com/lamenting-hawthorn/supermem
cp .env.example .env
# Edit .env with your vault path and API keys

docker compose up recall-mcp

---

Architecture: Four-Tier Retrieval

Query
  │
  ├─ Tier 1: SQLite FTS5 full-text search          ~1ms    always available
  ├─ Tier 2: Kuzu embedded graph expansion         ~5ms    optional
  ├─ Tier 3: ChromaDB vector similarity            ~50ms   optional
  └─ Tier 4: LLM agent fallback                   ~5-30s  always available

Tiers 1–3 never call an LLM. If tier 1 returns enough results, the rest are skipped entirely.

---

Features

• MCP server — stdio and HTTP transports; works with Claude Desktop, LM Studio, ChatGPT
• Hybrid storage — SQLite FTS5, Kuzu graph database, ChromaDB vector store
• Ambient memory injection — Claude Code hook system surfaces relevant context automatically
• TTL-based expiry — configure retention via RECALL_OBS_TTL_DAYS (default: 90 days)
• Parallel retrieval — all tiers run concurrently for sub-100ms queries
• Memory import connectors — ChatGPT, Notion, Nuclino, GitHub, Google Docs
• Worker HTTP API — search, indexing, health checks on :37777
• recall CLI — serve, chat, backup, restore, connect commands
• Docker support — single-command setup with docker compose

---

Requirements

• Python 3.11
• Optional: kuzu for graph tier, chromadb for vector tier, Docker for containerized setup

Links

• Documentation
• Contributing
• Changelog