claude-code-memory

Claude Code Memory is an MCP server plugin that provides a local, per-project cognitive memory system for Claude Code. It loads relevant project context at the start of a session, captures and stores structured memories during the session, can auto-recall memories when Bash errors occur, and periodically consolidates memories to keep the dataset clean and useful. All data stays local to the current project, scoped by the working directory, with memories categorized into episodic, semantic, procedural, working, and pattern types. The server exposes nine MCP tools (store, search, get, update, delete, list, batch-store, relate, graph) that Claude Code uses automatically to manage this memory, enabling faster context-driven responses and more robust error handling.

To use the server, install and run the MCP service, then start Claude Code as usual. During a session, Claude Code will auto-load context at SessionStart, automatically invoke the MCP tools as needed, surface error-context when Bash errors occur, and write a structured episodic summary when the session ends. Over time, the memory graph links related items and supports cross-project insights, while keeping data isolated to your current project directory.

Prerequisites:

• Node.js >= 18
• Git
• Access to the Claude Code CLI (plugin) and its installer as described in the README

Installation steps:

1. Clone the repository and enter the project directory: git clone https://github.com/d2a8k3u/claude-code-memory.git claude-memory cd claude-memory

2. Run the installer script which builds the MCP server and registers the integration: ./install.sh

3. Restart Claude Code after installation to ensure the plugin loads the MCP server correctly.

Optional first-run bootstrap:

• Run /memory-init in any project to populate initial memory from existing project files (e.g., README, package.json, CLAUDE.md, git history).

Environment considerations:

• The server defaults to a local SQLite store inside .claude/memory-db/memory.sqlite per project. You can customize the data directory via CLAUDE_MEMORY_DATA_DIR if needed.
• The embedding model is loaded once on first use (default all-MiniLM-L6-v2) and cached locally.

Notes and tips:

• This MCP server is designed to keep all memory local to the current project, scoped by the working directory.
• If you see a long startup time, it may be due to loading the embedding model for the first session.
• You can customize which embedding model to use by setting EMBEDDING_MODEL in the environment.
• The memory types help structure how information is stored and retrieved: episodic memories capture events, semantic memories store project facts, procedural memories describe actions-to-tasks, working stores the current session scratchpad, and pattern memories consolidate insights.
• If you encounter issues with memory loading, check the .claude/memory-db directory permissions and ensure the DB file memory.sqlite is writable.
• On first run, Claude Code may download a ~90 MB embedding model; this cache is shared per project and improves subsequent session speed.