claude-persistent-memory

Claude Persistent Memory provides a local, memory-backed store for Claude code sessions. It combines a hybrid search over memories (BM25 in SQLite and vector similarity via a shared embedding model) with LLM-driven structuring to persist memories across sessions and projects. The system supports on-demand retrieval (memory_search) and on-save operations (memory_save) so that memories can be organized, clustered, and retrieved with context. Tools are exposed through MCP endpoints and hooks, enabling memory-augmented prompting, pre/post tool context injection, and automatic clustering and validation workflows. Start by ensuring your Azure OpenAI credentials are configured if you plan to leverage the structuring features, as indicated in the Quick Start section, and then use the MCP tools to search, store, validate, and inspect memory data across your projects. The architecture isolates data per dataDir, so memories from one project do not contaminate another, while sharing a common embedding server for efficiency.

Prerequisites:

• Node.js >= 18 installed on your machine
• Access to Azure OpenAI if you intend to use LLM structuring (required for full features)
• Internet access for initial model download and MCP configuration

1. Install in your project

# 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 the package in your project
npm install @alex900530/claude-persistent-memory

2. After installation, follow the postinstall steps that the package performs automatically in your project:

• Generate .claude-memory.config.js (project config)
• Create and configure .mcp.json (MCP server registration)
• Create .claude/settings.json with lifecycle hooks
• Download and verify the embedding model (bge-m3, ~2GB)
• Register background services via your OS service manager (launchd/systemd)
• Update .gitignore as needed

3. Start the embedded servers

npm run embedding-server   # Start embedding/Memory-related server
npm run llm-server         # Start LLM server for structuring (Azure OpenAI)

4. If you skipped Azure credentials during install, you can configure the MCP via CLI later:

npx claude-persistent-memory

If you prefer to install from source, clone the repo, install dependencies, and follow the same steps to start the two services (embedding-server and llm-server) and then manually configure .mcp.json and .claude/settings.json as described in the README.

Tips and common issues:

• The embedding model (~2GB) is downloaded during installation. If the download is interrupted, run npm install again to retry.
• Memories are stored locally in SQLite databases per dataDir; ensure your filesystem has enough space for growth.
• When configuring Azure credentials, keep them secure and avoid committing them to version control.
• If you encounter connection issues between the MCP server and the embedding/LLM services, verify that the ports (e.g., for the embedding and LLM servers) are open and not blocked by a firewall.
• Use memory_search for retrieving context to the current prompt, memory_save to persist new memories, memory_validate to provide feedback, and memory_stats to monitor overall system health and memory distribution.
• For multi-project setups, consistently specify dataDir in your prompts to ensure correct routing to the intended project memory store.