memory-safe

MCP memory server for Claude Code. Knowledge graph in SQLite, local ONNX embeddings, token-budgeted retrieval.

Everything runs on your machine. No API keys, no network calls, no data leaves your system.

Why

Claude Code forgets everything between sessions. memory-safe gives it persistent memory that actually works:

• Semantic search — ask in natural language, get relevant results (94% Recall@1)
• Token budget — never blows up your context window (100% budget adherence)
• Knowledge graph — entities and relationships, not just flat text
• Memory decay — old memories compress automatically, no manual cleanup
• 1,019 tokens overhead — half the cost of @modelcontextprotocol/server-memory (2,045 tokens)

Install

Requires Node.js 20+.

Claude Code (recommended)

One command — adds memory-safe as an MCP server directly:

claude mcp add memory-safe -- npx -y memory-safe

Claude Code Plugin

Install as a plugin from the GitHub repo:

claude plugin marketplace add eljoesb/memory-safe
claude plugin install memory-safe@eljoesb/memory-safe

Manual configuration

Add to your Claude Code MCP config (~/.claude.json or project .claude/settings.json):

{
  "mcpServers": {
    "memory-safe": {
      "command": "npx",
      "args": ["-y", "memory-safe"]
    }
  }
}

With a custom database path:

{
  "mcpServers": {
    "memory-safe": {
      "command": "npx",
      "args": ["-y", "memory-safe", "--db=/path/to/my/memory.db"]
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "memory-safe": {
      "command": "npx",
      "args": ["-y", "memory-safe"]
    }
  }
}

npm

npm install memory-safe

Default database location: ~/.memory-safe/memory.db

Tools

memory-safe exposes 11 MCP tools. Total overhead: ~1,019 tokens.

Core

Knowledge Graph

System

How It Works

Retrieval

Recall uses a multi-signal scoring formula:

score = 0.60 * similarity      # cosine similarity via ONNX embeddings
      + 0.20 * recency         # days since last access (0-30 day window)
      + 0.10 * frequency       # access count (normalized)
      + 0.10 * connectivity    # entity link count in knowledge graph
      - decay_penalty           # 0.1 per decay level

Results are packed greedily into the token budget with a 0.85 safety multiplier. 15% of the budget is reserved for knowledge graph context.

Embeddings

Model: Xenova/all-MiniLM-L6-v2 (384 dimensions), running locally via ONNX through @huggingface/transformers. Lazily loaded on first use — tools like status and configure respond instantly without waiting for model download.

If the model fails to load, recall falls back to keyword similarity.

Memory Decay

Automatic compression based on access patterns. No LLM calls — pure extractive summarization:

Decay pressure is compared against an importance score (access frequency + entity links + recency). Only memories with significantly more pressure than importance get compressed.

Token Budget

Every recall respects the token budget (default: 2,000 tokens):

1. Nominal budget * 0.85 safety multiplier = effective budget
2. 85% for memory content, 15% reserved for graph context
3. Greedy packing: highest-scored memories first, stop when budget exhausted
4. Always returns at least one memory

Benchmarks

Solo Performance

50 diverse test memories, 10 queries, token budget 2,000:

Comparison vs @modelcontextprotocol/server-memory

50 memories, 20 queries x 5 runs. Two query types: Semantic (natural language) and Keyword (exact substring):

Key takeaway: memory-safe finds the right memory 94% of the time from natural language queries. server-memory requires exact keyword matches — it returns empty results for natural language queries because it uses substring search, not semantic search.

server-memory is faster on keyword lookups because it does simple string matching. memory-safe's ONNX embedding model adds ~3ms overhead per query but enables understanding what you mean, not just what you typed.

Run Benchmarks

# Build first
npm run build

# Solo benchmark
npm run bench

# Multi-server comparison (all formats)
npm run bench:compare
npm run bench:compare -- --format=markdown
npm run bench:compare -- --format=json

# Single server, fewer runs
npm run bench:compare -- --servers=memory-safe --runs=1

Architecture

src/
  index.ts              CLI entry point (--db=, --telemetry)
  server.ts             11 MCP tool registrations
  db/
    connection.ts       sql.js WASM singleton, debounced persistence
    schema.ts           5 tables, migrations, timestamp helpers
  memory/
    store.ts            Store + auto-extract entities from content
    retrieve.ts         Token-budgeted semantic recall (6-step pipeline)
    decay.ts            Extractive summarization decay engine
  embeddings/
    onnx.ts             Lazy ONNX pipeline (all-MiniLM-L6-v2, 384 dims)
  graph/
    entities.ts         Entity CRUD (upsert, search, link)
    relations.ts        Relation CRUD (typed, weighted, bidirectional)
    query.ts            BFS traversal (depth 2, max 30 nodes)
  tokenizer/
    counter.ts          cl100k_base token counting + truncation
  utils/
    config.ts           Key-value config store
    serialization.ts    Float32Array ↔ Buffer, cosine similarity
    telemetry.ts        Opt-in local telemetry (no network)
bench/
  corpus.ts             50 test memories + 3 query sets
  suite.ts              Solo benchmark (precision, tokens, latency)
  comparison.ts         Multi-server MCP comparison runner
  results.ts            ASCII / Markdown / JSON formatters
  adapters/
    base.ts             StdioClientTransport lifecycle
    memory-safe.ts      Adapter for memory-safe
    mcp-server-memory.ts  Adapter for @modelcontextprotocol/server-memory

Database

sql.js (WASM) — no native dependencies, works everywhere. Trade-off: ~2-3x slower than better-sqlite3, but zero compilation issues.

Tables: memories, entities, relations, memory_entities (junction), config.

Persistence: in-memory WASM DB exported to disk via debounced writes (1s after last mutation).

Known sql.js Limitations

• No datetime('now') in DEFAULT — timestamps generated in code
• No json_patch() — manual JSON merge in code
• No FTS5 — LIKE queries for keyword search

Configuration

Set via the configure tool or directly in the config table.

CLI Options

memory-safe [options]

  --db=/path/to/db.db    Custom database path (default: ~/.memory-safe/memory.db)
  --telemetry            Enable local telemetry logging (~/.memory-safe/telemetry.log)

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Run tests
npm test

# Benchmarks
npm run bench              # Solo
npm run bench:compare      # Multi-server comparison
npm run bench:overhead     # Tool token overhead measurement

License

MIT