claude-total-memory

Claude Total Memory provides a persistent local memory store for Claude Code and the OpenAI Codex CLI via the MCP protocol. It replaces the default ephemeral session memory by maintaining a local database of decisions, solutions, lessons, facts, and conventions that can be recalled across sessions. This enables Claude to remember architecture, design decisions, and context between runs, improving consistency and reducing repetitive debugging. You’ll access the server through a client that supports MCP and can then query, recall, and manage stored knowledge using the 20 built-in MCP tools, plus the web dashboard for monitoring and exploration. The included self-improving agent and privacy features help refine responses over time while redacting sensitive data before storage. To use it, configure your MCP client to connect to the server’s address and ensure the environment variables point to your local memory store and embedding model, then start the server and begin interacting with Claude’s memory-aware workflows.

Prerequisites:

• Python 3.10+ installed on your system
• Internet access to install Python packages
• Git installed to clone the repository (optional if you already have the code)

Option A: One-command install (from repository)

• Clone the repo and run the installer that sets up a virtual environment and dependencies:

git clone https://github.com/vbcherepanov/claude-total-memory.git
cd claude-total-memory
bash install.sh

Option B: Manual setup

1. Create and activate a Python virtual environment:

python3 -m venv .venv
source .venv/bin/activate

2. Install required packages:

pip install "mcp[cli]>=1.0.0" chromadb sentence-transformers

3. Install or prepare the embedding model and resources as needed by the project (per README guidance).

4. Configure the MCP server in your Claude Code settings (see the snippet in the README). Ensure paths are absolute and expanded.

5. Start the server via your MCP client configuration by pointing to the server script, for example using the mcp client after configuration.

Tips and common issues:

• Ensure you use absolute, fully expanded paths for all server references (no ~ or %USERPROFILE% shorthand).
• The embedding model is configurable via EMBEDDING_MODEL; common choices include all-MiniLM-L6-v2. If you switch models, verify compatibility with your memory indexing and performance needs.
• The CLAUDE_MEMORY_DIR controls where memories are stored locally; ensure the directory exists and is writable by your user.
• The web dashboard for this server is typically hosted locally (e.g., localhost:37737); confirm firewall/network settings if you access remotely.
• If you encounter dependency issues, re-create the venv and reinstall with a clean environment.
• The MCP tools provide 20 capabilities for memory management, search, and recall; consult the project docs for specifics on each tool’s syntax and options.