claudecode-infinite-memory

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

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

| Variable | Default | Description | |----------|---------|-------------| | MCP_MEMORY_DB_PATH | ./memory.sqlite | SQLite database path | | MCP_MEMORY_CLAUDE_HISTORY_PATH | ~/.claude/history.jsonl | Claude Code session history file | | MCP_MEMORY_SESSIONS_PATH | ~/.claude/projects | Directory containing session JSONL files | | MCP_MEMORY_KNOWLEDGE_PATH | _(empty, disabled)_ | Knowledge directory path; put .md files here for auto-indexing | | MCP_MEMORY_DEFAULT_LIMIT | 5 | Default search result count | | MCP_MEMORY_MAX_LIMIT | 20 | Maximum search result count | | MCP_MEMORY_CHUNK_TOKENS | 400 | Knowledge indexing chunk size (approximate tokens) | | MCP_MEMORY_CHUNK_OVERLAP_TOKENS | 80 | Chunk overlap size (approximate tokens) | | MCP_MEMORY_SYNC_COOLDOWN_MS | 5000 | Cooldown before incremental sync on search (ms) | | MCP_MEMORY_SYNC_ON_START | true | Full sync on server startup | | MCP_MEMORY_WATCH | false | Enable file watcher for knowledge directory | | MCP_MEMORY_WATCH_DEBOUNCE_MS | 1500 | File watcher debounce interval (ms) |

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

| Layer | Source | Write Method | Index Method | Characteristics | |-------|--------|-------------|-------------|-----------------| | Layer 1 | Session JSONL files | Auto (Claude Code) | FTS5 chunked index | Zero-config, session transcript search | | Layer 2 | Knowledge .md files | Manual (user drops files) | FTS5 chunked index (approx. tokens) | High precision, requires file maintenance | | Layer 3 | memory_store calls | Claude Code / user-triggered | FTS5 + triggers | Precise, driven by CLAUDE.md instructions |

See ARCHITECTURE.md for detailed technical documentation.