Melchizedek

Persistent memory for Claude Code. Automatically indexes every conversation and provides production-grade hybrid search (BM25 + vectors + reranker) via MCP tools. 100% local, zero config, zero API keys, zero invoice.

Why Melchizedek?

Claude Code forgets everything between sessions - and knows nothing about your other projects. Melchizedek fixes both.

It runs silently in the background - indexing your conversations as you work - then gives Claude the ability to search across your entire history, across all projects: past debugging sessions, architectural decisions, error solutions, code patterns.

No cloud. No API keys. No config. Plug and ask.

How it works

~/.claude/projects/**/*.jsonl       (your conversation transcripts - read-only)
        |
        v
  SessionEnd hook                   (auto-triggers after each session)
        |
        v
  +-----------------+
  |  Indexer         |    Parse JSONL -> chunk pairs -> SHA-256 dedup
  |  (better-sqlite3)|    FTS5 tokenize -> vector embed (optional)
  +-----------------+
        |
        v
  ~/.melchizedek/memory.db           (single SQLite file, WAL mode)
        |
        v
  +-----------------+
  |  MCP Server      |    16 search & management tools
  |  (stdio)         |    Hybrid: BM25 + vectors + RRF + reranker
  +-----------------+
        |
        v
  Claude Code                       (searches your history via MCP)

Daemon singleton - multi-instance support

When you open multiple Claude Code windows, Melchizedek shares a single daemon process across all of them - 1 database, 1 embedder, 1 reranker loaded once in memory.

The server starts in 3 phases:

1. Try connecting to an existing daemon (Unix socket on macOS/Linux, named pipe on Windows)
2. Auto-start the daemon if none is running
3. Fallback to local standalone mode if the daemon can't start

This is transparent - Claude Code sees a normal stdio MCP server. Set M9K_NO_DAEMON=1 or --no-daemon to disable daemon mode.

Search pipeline - 4 levels of graceful degradation

Every layer is optional. The plugin works with BM25 alone and gets better as more components are available.

Performance

Measured with npm run bench - 100 sessions, 1 000 chunks, on a single SQLite file.

Installation

Claude Code plugin marketplace

claude plugin install melchizedek

npm (global)

npm install -g melchizedek

Create a file (e.g. /tmp/melchizedek-mcp.json):

{
  "mcpServers": {
    "melchizedek": {
      "command": "melchizedek-server"
    }
  }
}

claude --mcp-config /tmp/melchizedek-mcp.json

npx (no install)

Create a file (e.g. /tmp/melchizedek-mcp.json):

{
  "mcpServers": {
    "melchizedek": {
      "command": "npx",
      "args": ["melchizedek-server"]
    }
  }
}

claude --mcp-config /tmp/melchizedek-mcp.json

From source (contributors)

git clone https://github.com/louis49/melchizedek.git
cd melchizedek
npm install && npm run build

Then launch Claude Code with the generated .mcp.json:

claude --mcp-config .mcp.json

Note: npm run build generates .mcp.json with absolute paths to dist/server.js. The claude mcp add command may not work reliably due to known Claude Code plugin bugs - --mcp-config is the tested method.

Setting up hooks (automatic indexing)

The MCP server provides search tools, but hooks are what trigger automatic indexing. Without hooks, you'd need to manually index sessions.

For marketplace installs, hooks are configured automatically. For npm/npx/source installs, add the following to ~/.claude/settings.json:

{
  "hooks": {
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node /absolute/path/to/dist/hooks/session-end.js"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node /absolute/path/to/dist/hooks/session-end.js"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node /absolute/path/to/dist/hooks/session-start.js"
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node /absolute/path/to/dist/hooks/pre-compact.js"
          }
        ]
      }
    ]
  }
}

Replace /absolute/path/to with the actual path to your Melchizedek installation (e.g. $(npm root -g)/melchizedek for global installs, or your clone directory for source installs).

After installation, restart Claude Code. That's it - indexing starts automatically.

Enhanced Search (Optional)

Melchizedek works out of the box with BM25 keyword search. Text embeddings (MiniLM) download automatically on first use for semantic search. The optional backends below add GPU-accelerated code embeddings and reranking for maximum search quality.

Recommended Setup by Platform

macOS (Apple Silicon)

ONNX Runtime has no Metal backend for Node.js - transformers-js runs CPU only on macOS. MiniLM is small enough that this isn't a bottleneck. For code embeddings, Ollama provides GPU acceleration via Metal.

Linux (NVIDIA)

To enable CUDA for text embeddings: npm install onnxruntime-node-gpu (replaces the CPU-only onnxruntime-node, no code changes needed). Requires NVIDIA drivers + CUDA Toolkit 12.4+.

Windows (NVIDIA)

Ollama auto-detects NVIDIA GPUs after installation. For reranking, node-llama-cpp has prebuilt CUDA binaries - no compilation needed. llama-server is also an option but requires Visual Studio Build Tools to compile.

CPU-only (any platform)

Everything works on CPU - BM25 search is unaffected (no GPU needed). Code embedding is slow without GPU; disable it with "embeddingCodeEnabled": false if speed is a concern.

Recommended models reference

All Transformers.js models auto-download from Hugging Face on first use. GGUF models must be downloaded manually.

Language note: The default text embedder (MiniLM) is multilingual - it works well for non-English conversations. The default CPU reranker (ms-marco) is English-only - for other languages, use a GGUF reranker (BGE m3 or Qwen3, both multilingual). BM25 keyword search works for any language via FTS5 Unicode tokenization.

Tested embedding models

You can switch embedding models via m9k_config key="embeddingTextModel" value='"model-key"'. All models below have been tested end-to-end (load, embed, normalize, dimension check). Any ONNX-compatible HuggingFace model not listed here can also be used - Melchizedek will auto-detect dimensions and pooling from the model cache.

Transformers.js (local ONNX, zero config)

Custom models: Set embeddingTextModel to any HuggingFace model ID (e.g. "org/my-model"). Melchizedek resolves in order: built-in registry, HF cache metadata (config.json), then dynamic fallback (mean pooling, dimensions probed at runtime).

Ollama (GPU-accelerated, any model)

Any Ollama embedding model works - no registry needed. Dimensions are auto-detected. Tested models:

Other popular choices (untested but expected to work):

Browse all: ollama.com/search?c=embedding

Reranker models

Setting up Ollama

Ollama provides GPU-accelerated code embeddings on all platforms.

# macOS  - download the .dmg from https://ollama.com/download/mac
# Windows - download installer from https://ollama.com/download
# Linux
curl -fsSL https://ollama.com/install.sh | sh

# Then pull the code embedding model
ollama pull unclemusclez/jina-embeddings-v2-base-code

Then tell Melchizedek to use Ollama for code embeddings:

m9k_config key="embeddingCodeBackend" value='"ollama"'
m9k_config key="embeddingCodeModel" value='"unclemusclez/jina-embeddings-v2-base-code"'

Setting up a GPU reranker

The reranker is a cross-encoder that re-scores results after BM25 + vector fusion. It's optional - search works without it - but it improves precision on ambiguous queries. The default (transformers-js, CPU) works out of the box. For GPU acceleration:

Option A - llama-server (recommended)

# 1. Compile llama.cpp
git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
cmake -B build -DGGML_METAL=ON    # macOS Metal
# cmake -B build -DGGML_CUDA=ON   # Linux/Windows CUDA
cmake --build build --config Release -j

# 2. Download a GGUF reranker model (pick one)
# BGE Reranker v2 M3 (~440 MB) - recommended
wget https://huggingface.co/gpustack/bge-reranker-v2-m3-GGUF/resolve/main/bge-reranker-v2-m3-Q4_K_M.gguf
# Or: Qwen3 Reranker 0.6B (~640 MB) - alternative
# wget https://huggingface.co/ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF/resolve/main/qwen3-reranker-0.6b-q8_0.gguf

# 3. Run the server
./build/bin/llama-server --rerank --pooling rank \
  -m bge-reranker-v2-m3-Q4_K_M.gguf --port 8012

Then configure Melchizedek - either edit ~/.melchizedek/config.json or ask Claude:

m9k_config key="rerankerBackend" value='"llama-server"'
m9k_config key="rerankerUrl" value='"http://localhost:8012"'

Verify: curl http://localhost:8012/health should return {"status":"ok"}. Hot-reload works - no need to restart Melchizedek.

Option B - node-llama-cpp

npm install -g node-llama-cpp
mkdir -p ~/.melchizedek/models
cp bge-reranker-v2-m3-Q4_K_M.gguf ~/.melchizedek/models/

No config needed - Melchizedek auto-detects GGUF files matching bge-reranker* or qwen*reranker* in ~/.melchizedek/models/.

Backend detection priority

Reranker: llama-server (if URL set + healthy) > node-llama-cpp (if GGUF found) > transformers-js (CPU) > none.

Check active backends: m9k_info shows the current pipeline in its output.

Alternative configurations

MCP Tools

Search (start here)

Progressive retrieval pattern - search returns ~50 tokens/result, context ~200-300, full ~500-1000. Start with m9k_search, drill down only when needed. 4x token savings vs loading everything.

Context-aware ranking - results from your current project (×1.5) and current session (×1.2) are automatically promoted. Cross-project results remain visible.

Specialized search

Memory management

Usage guide

Configuration

Zero config by default. Everything is tunable via m9k_config or environment variables.

How is this different?

	Melchizedek	claude-historian-mcp	claude-mem	episodic-memory	mcp-memory-service
Philosophy	Search engine - indexes everything, you search	Search engine - scans JSONL on demand	Notebook - AI compresses & saves	Search engine	Notebook - AI decides what to store
Indexes raw conversations	Yes (JSONL transcripts)	Yes (direct JSONL read, no persistent index)	Compressed summaries	Yes (JSONL)	No (manual store_memory)
Retroactive on install	Yes (backfills all history)	Yes (reads existing files)	No	Yes	No (empty at start)
Search	BM25 + vectors + RRF + reranker	TF-IDF + fuzzy matching	FTS5 + ChromaDB	Vectors only	BM25 + vectors
Progressive retrieval	3 layers (search/context/full)	No	No	No	No
100% offline	Yes	Yes	No (needs API for compression)	Yes	Yes
Single-file storage	SQLite	None (reads raw JSONL)	SQLite + ChromaDB	SQLite	SQLite-vec
Zero config	Yes	Yes	Yes	Yes	Yes
MCP tools	16	10	4	2	12
License	MIT	MIT	AGPL-3.0	MIT	Apache-2.0
Dual embedding (text + code)	Yes (MiniLM + Jina Code)	No	No	No	No
Configurable models	Yes (Transformers.js or Ollama)	No	No (Chroma internal)	No (hardcoded)	Yes (ONNX, Ollama, OpenAI, Cloudflare)
Reranker	Cross-encoder (ONNX, GGUF, or HTTP)	No	No	No	Quality scorer (not search reranker)
Privacy	All local, <private> tag redaction	All local	Sends data to Anthropic API	All local	All local
Multi-instance	Singleton daemon - N Claude windows share 1 process (Unix socket / Windows named pipe, local fallback)	N separate processes	Shared HTTP worker (:37777)	N separate processes	Shared HTTP server

Inspirations

This project stands on the shoulders of others. Key ideas borrowed from:

Project	What we took
CASS	RRF hybrid fusion, SHA-256 dedup, auto-fuzzy fallback
claude-historian-mcp	Specialized MCP tools (file_history, error_solutions)
claude-diary	PreCompact hook (archive before /compact)

Memory usage

Melchizedek loads ML models for embeddings and reranking. Here's what to expect:

The embed-worker is a child process that runs during initial indexing and exits when done - its memory is fully reclaimed.

About virtual memory (VSZ): macOS Activity Monitor may show very large virtual memory numbers (400+ GB per process). This is normal - ONNX Runtime reserves large virtual address ranges via mmap without actually using physical RAM. The real consumption is the RSS column above. Only RSS reflects actual memory pressure.

To reduce memory usage:

• "embeddingCodeEnabled": false - skip code embeddings (saves ~2.5 GB during backfill)
• "embeddingsEnabled": false - BM25 only, ~70 MB total
• Use Ollama for code embeddings - offloads to a separate process with GPU acceleration

Known issues

• Session boost inactive - Claude Code currently sends an empty session_id in the SessionStart hook stdin payload, preventing the ×1.2 session boost from working. The ×1.5 project boost is unaffected and provides the primary context-aware ranking. Related upstream issues: #13668 (empty transcript_path), #9188 (stale session_id). Melchizedek's session boost code is tested and ready, and will activate automatically when the upstream fix lands.

Privacy

• Zero telemetry. No tracking, no analytics, no network calls (except optional lazy model download).
• Read-only on transcripts. Never writes to ~/.claude/projects/. All data in ~/.melchizedek/.
• <private> tag support. Content between <private>...</private> is replaced with [REDACTED] before indexing.
• Local-only. Your conversations never leave your machine.

Requirements

• Node.js >= 20
• Claude Code >= 2.0
• macOS, Linux, or Windows

License

MIT

"Without father, without mother, without genealogy, having neither beginning of days nor end of life."

• Hebrews 7:3

Built by @louis49