Claude Persistent Memory

Give Claude Code long-term memory that persists across sessions.
Hybrid BM25 + vector semantic search · LLM-driven structuring · Multi-project isolation

English | 中文

Features • Quick Start • Architecture • MCP Tools • Configuration • Contributing

Features

Hybrid Search — BM25 full-text (FTS5) + vector semantic similarity (sqlite-vec), combined ranking (0.7 vector + 0.3 BM25)

4-Channel Retrieval — Pull (MCP tools on demand) + Push (auto-inject via hooks on user prompt, pre-tool, post-tool)

LLM Structuring — Memories auto-structured into <what>/<when>/<do>/<warn> XML format via Azure OpenAI

Multi-Project Isolation — Single shared embedding server routes requests by dataDir. Each project has its own database, no cross-contamination.

Automatic Clustering — Similar memories grouped, mature clusters merged into high-confidence consolidated memories

Confidence Scoring — Memories gain/lose confidence through validation feedback and usage patterns

Local-First — All data stored locally in SQLite. Your memories never leave your machine.

Quick Start

Install

# Set Azure OpenAI credentials (required for LLM structuring)
export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com"
export AZURE_OPENAI_KEY="your-api-key"

# Install in any project
npm install @alex900530/claude-persistent-memory

The postinstall script automatically:

1. Generates .claude-memory.config.js (project config)
2. Configures .mcp.json (MCP server registration)
3. Configures .claude/settings.json (5 lifecycle hooks)
4. Downloads and verifies the embedding model (bge-m3, ~2GB)
5. Registers background services via launchd/systemd
6. Updates .gitignore

Open Claude Code in the project directory — memory is ready.

Note: The embedding model (~2GB) is downloaded and verified during install. If the download is interrupted or the model is corrupt, install will fail. Simply re-run npm install to retry.

Configure later

If you skipped Azure credentials during install:

npx claude-persistent-memory

Install from source

git clone https://github.com/MIMI180306/claude-persistent-memory.git
cd claude-persistent-memory
npm install
cp config.default.js config.js
# Edit config.js with your Azure credentials

# Start services
npm run embedding-server   # Terminal 1
npm run llm-server         # Terminal 2

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Claude Code Session                     │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Pull Channel (on demand)         Push Channels (auto)      │
│  ┌───────────────────┐    ┌──────────────────────────────┐  │
│  │ MCP Server        │    │ UserPromptSubmit Hook        │  │
│  │ memory_search     │    │ PreToolUse Hook              │  │
│  │ memory_save       │    │ PostToolUse Hook             │  │
│  │ memory_validate   │    │ PreCompact Hook (analysis)   │  │
│  │ memory_stats      │    │ SessionEnd Hook (clustering) │  │
│  └────────┬──────────┘    └──────────────┬───────────────┘  │
│           │                              │                  │
│           └──────────┬───────────────────┘                  │
│                      │  dataDir routing                     │
│                      ▼                                      │
│  ┌───────────────────────────────────────────────────────┐  │
│  │            Shared Embedding Server (TCP :23811)       │  │
│  │            bge-m3 model (shared across projects)      │  │
│  │            Database pool (per-project by dataDir)     │  │
│  └───────────────────────────────────────────────────────┘  │
│                      │                                      │
│       ┌──────────────┼──────────────┐                       │
│       ▼              ▼              ▼                       │
│  ┌─────────┐   ┌─────────┐   ┌─────────┐                   │
│  │Project A│   │Project B│   │Project C│                    │
│  │memory.db│   │memory.db│   │memory.db│                    │
│  └─────────┘   └─────────┘   └─────────┘                   │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │            LLM Server (TCP :23812)                    │  │
│  │            Azure OpenAI GPT-4.1                       │  │
│  └───────────────────────────────────────────────────────┘  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Multi-Project Support

The embedding server is shared across all projects. Each request carries a dataDir parameter that routes to the correct project's database:

• Embedding model — loaded once, shared across all projects (~2GB RAM)
• Database connections — pooled per dataDir, created on first access (~5ms)
• No cross-contamination — searching in Project A never returns Project B's memories

MCP Tools

Hooks

Memory Types

Memory Lifecycle

Save       → memory_save or auto-extract from transcript
Structure  → LLM converts to <what>/<when>/<do>/<warn> XML
Embed      → bge-m3 generates 1024-dim vector
Dedupe     → Jaccard similarity >= 0.95 → update existing
Search     → 0.7 * vectorSimilarity + 0.3 * normalizedBM25
Validate   → memory_validate adjusts confidence ±
Cluster    → similar memories auto-grouped
Merge      → mature clusters consolidated into single memory

Uninstall

npx claude-persistent-memory-uninstall

Or manually: remove memory from .mcp.json, remove memory hooks from .claude/settings.json, then npm uninstall @alex900530/claude-persistent-memory. The .claude-memory/ data directory is preserved — delete manually if no longer needed.

Configuration

All settings in config.default.js (override via .claude-memory.config.js):

module.exports = {
  embeddingPort: 23811,          // TCP port for embedding server
  llmPort: 23812,                // TCP port for LLM server
  dataDir: './data',             // memory.db location (per-project)
  azure: {
    endpoint: process.env.AZURE_OPENAI_ENDPOINT,
    apiKey: process.env.AZURE_OPENAI_KEY,
    deployment: 'gpt-4-1',
  },
  embedding: {
    model: 'Xenova/bge-m3',     // 1024 dimensions, 8192 token context
    dimensions: 1024,
  },
  search: {
    maxResults: 3,               // top-K results per query
    minSimilarity: 0.6,          // vector similarity threshold
  },
  cluster: {
    similarityThreshold: 0.70,   // min similarity to join a cluster
    maturityCount: 5,            // memories needed for mature cluster
  },
};

Project Structure

claude-persistent-memory/
├── bin/
│   ├── setup.js                  # postinstall + interactive setup
│   └── uninstall.js              # cleanup script
├── hooks/
│   ├── user-prompt-hook.js       # UserPromptSubmit → memory injection
│   ├── pre-tool-memory-hook.js   # PreToolUse → memory injection
│   ├── post-tool-memory-hook.js  # PostToolUse → memory injection
│   ├── pre-compact-hook.js       # PreCompact → transcript analysis
│   └── session-end-hook.js       # SessionEnd → clustering + merging
├── lib/
│   ├── memory-db.js              # SQLite + FTS5 + sqlite-vec + connection pool
│   ├── embedding-client.js       # TCP client for embedding server
│   ├── llm-client.js             # TCP client for LLM server
│   ├── compact-analyzer.js       # Transcript → memory extraction
│   └── utils.js
├── services/
│   ├── embedding-server.js       # Shared embedding service (bge-m3)
│   ├── llm-server.js             # LLM proxy (Azure OpenAI)
│   └── memory-mcp-server.js      # MCP server (stdio, per-project)
├── config.default.js
└── package.json

Requirements

• Node.js >= 18
• macOS or Linux
• ~2GB RAM for embedding model (bge-m3)
• ~2GB disk for model cache (~/.cache/huggingface/transformers-js/)
• Azure OpenAI API access (for LLM structuring)

Notes

• LLM provider: Currently supports Azure OpenAI only. Modify services/llm-server.js for other providers.
• Ports: Embedding and LLM servers default to TCP 23811 / 23812. Change in config if conflicting.
• Multi-project: All projects share one embedding server process. The model is loaded once; databases are pooled by dataDir.
• Data: .claude-memory/ directory (containing memory.db and logs) is auto-created and gitignored per project.

Contributing

Contributions welcome! Please read the Contributing Guide before submitting a PR.

License

MIT