Installation¶

Requirements¶

The hooks require Bash and Python 3, even if jq is installed: Python parses session transcripts and handles JSON when jq is absent. jq is optional. The hooks try python3, then python, then the Windows launcher py -3, and verify that the command runs Python 3.

On Windows, Claude Code runs hooks in Git Bash. Git for Windows does not include Python or jq, so install Python 3 and make it available on the hooks' PATH. The python3 and python commands under %LOCALAPPDATA%\Microsoft\WindowsApps may be Microsoft Store App Execution Aliases that print "Python was not found" instead of running Python. The hooks skip nonworking aliases and try the next command.

Restart Claude Code after installing Python or changing PATH, so the hooks inherit the updated environment. If no usable interpreter is found, SessionStart reports ERROR: no working Python 3 found and memory capture disabled.

Install from Marketplace (recommended)¶

# 1. In Claude Code, add the marketplace and install the plugin
/plugin marketplace add zilliztech/memsearch
/plugin install memsearch

# 2. Restart Claude Code to activate the plugin (exit and reopen)

# 3. Have a conversation, then exit. Check your memories:
cat .memsearch/memory/$(date +%Y-%m-%d).md

# 4. Start a new session -- Claude automatically remembers!

Install from Source (development)¶

git clone https://github.com/zilliztech/memsearch.git
cd memsearch && uv sync
claude --plugin-dir ./plugins/claude-code

First-time ONNX model download

The plugin defaults to ONNX bge-m3 embedding -- no API key required, runs locally on CPU. On first launch, the model (~558 MB) is downloaded from HuggingFace Hub. Pre-download it manually:

uvx --from 'memsearch[onnx]' memsearch search --provider onnx "warmup" 2>/dev/null || true

If the download is slow, set export HF_ENDPOINT=https://hf-mirror.com to use a mirror.

Configuration¶

The plugin defaults to ONNX bge-m3 embedding (no API key, CPU-only). To use a different provider:

memsearch config set embedding.provider openai
export OPENAI_API_KEY="sk-..."

For Milvus backend configuration, see Getting Started -- Milvus Backends.

Updating¶

Marketplace installs use Claude Code's plugin update commands:

# Refresh marketplace metadata, then update the installed plugin
claude plugin marketplace update memsearch-plugins
claude plugin update memsearch

Restart Claude Code after updating so the new hooks and skill files are loaded.

For source installs, pull the latest repo and restart Claude Code with the same plugin directory:

cd memsearch
git pull
uv sync
claude --plugin-dir ./plugins/claude-code

Uninstall¶

claude plugin uninstall memsearch --keep-data

The uninstall command removes the Claude Code plugin integration. Your project memories under .memsearch/memory/ are not deleted.