claudecode-infinite-memory

A lightweight MCP memory server built on SQLite + FTS5, providing cross-session long-term memory for Claude Code. Supports three-source merged retrieval: long-term memories, session history, and knowledge base indexing.

Features

• Long-term memory — Store and retrieve persistent memories across sessions with deduplication

• Session indexing — Automatically indexes Claude Code session transcripts (user + assistant messages)

• Knowledge base — Drop .md files in a folder and get them auto-indexed with FTS5

• Three-source search — Queries all three sources simultaneously with importance-weighted re-ranking

• Incremental sync — Only re-indexes files that actually changed (hash + mtime detection)

• Zero external model dependencies — Pure keyword-based retrieval using FTS5 BM25, no embedding models needed

Related MCP server: recall-mcp

How It Works

graph BT
    subgraph Data Sources
        CC["Claude Code Sessions\nauto-generated .jsonl"]
        MD["Knowledge Files\nuser-managed .md"]
        STORE["memory_store() calls\nfrom Claude Code"]
    end

    subgraph Index & Storage
        SESS["Layer 1: session_chunks\nFTS5 indexed"]
        KNOW["Layer 2: knowledge_chunks\nFTS5 indexed"]
        MEM["Layer 3: memories\nFTS5 indexed"]
    end

    CC -->|auto sync| SESS
    MD -->|auto sync| KNOW
    STORE -->|store + dedup| MEM

    SESS --> SEARCH["memory_search(query)"]
    KNOW --> SEARCH
    MEM --> SEARCH

    subgraph Claude Code Client
        USER["User Input"] --> LLM["Claude LLM"]
    end

    SEARCH -->|results| LLM

Requirements

• Node.js 18+ (20+ recommended)

• Run npm install in the project directory

Quick Start

# Development mode (stdio)
npm run dev

# Production build
npm run build
npm start

Integration with Claude Code

Add the following to your Claude Code MCP config (~/.claude.json):

{
  "mcpServers": {
    "claudecode-infinite-memory": {
      "command": "npm",
      "args": ["--prefix", "/path/to/claudecode-infinite-memory", "run", "-s", "dev"],
      "env": {
        "MCP_MEMORY_DB_PATH": "/path/to/claudecode-infinite-memory/memory.sqlite",
        "MCP_MEMORY_CLAUDE_HISTORY_PATH": "~/.claude/history.jsonl",
        "MCP_MEMORY_SESSIONS_PATH": "~/.claude/projects",
        "MCP_MEMORY_KNOWLEDGE_PATH": "/path/to/your/knowledge-base",
        "MCP_MEMORY_DEFAULT_LIMIT": "5",
        "MCP_MEMORY_MAX_LIMIT": "20",
        "MCP_MEMORY_WATCH": "false"
      }
    }
  }
}

Replace /path/to/... with your actual paths. Merge into your existing mcpServers if needed.

Tools

memory_store(text, category?)

Store a long-term memory entry.

• text (required) — The memory content

• category (optional) — One of: preference, fact, decision, entity, other

• Deduplication — Uses sha256(text + category) as a unique hash. Duplicate writes return action: "duplicate", successful writes return action: "stored".

memory_search(query, limit?)

Search across all three data sources with merged ranking.

Data sources:

1. Long-term memories (memories table) — FTS5 full-text search with BM25 ranking, LIKE fallback

2. Session history (session JSONL files) — FTS5 full-text search on indexed session transcripts

3. Knowledge base (knowledge_chunks table) — FTS5 full-text search on chunked .md files

Ranking strategy:

• Each source produces TopK candidates (limit * 5, capped at 50)

• Results are re-ranked: finalScore = baseScore + importanceBoost

• Importance boost factors: source weight + structure weight + category weight

• Final results sorted by finalScore desc, then createdAt desc

memory_forget(id)

Delete a specific memory entry by ID. Returns { deleted: true | false }.

Environment Variables

Knowledge Base (Layer 2)

Set MCP_MEMORY_KNOWLEDGE_PATH to a directory containing .md files.

How it works:

• On startup — Full scan, approximate token-based chunking (default 400 tokens/chunk, 80 overlap), FTS5 indexing

• On search — Cooldown check + change detection, incremental rebuild if needed

• Incremental sync — mtime change triggers hash comparison, only changed files are re-chunked

• Deletion sync — Files removed from disk are automatically cleaned from the index

• Config change rebuild — Changing chunk parameters triggers a full rebuild (detected via knowledge_meta)

• File watcher (optional) — Set MCP_MEMORY_WATCH=true for fs.watch-based monitoring with debounce

When MCP_MEMORY_KNOWLEDGE_PATH is not set, this feature is silently skipped.

Three-Layer Memory Architecture

See ARCHITECTURE.md for detailed technical documentation.