CCCMemory

An MCP server that gives Claude long-term memory by indexing conversation history with semantic search, decision tracking, and cross-project search.

What's New in v2.0

Version 2.0 brings major improvements to search quality and accuracy:

• Smart Chunking - Long messages are now split at sentence boundaries, ensuring full content is searchable (previously truncated at 512 tokens)
• Hybrid Search - Combines semantic search with full-text search using Reciprocal Rank Fusion (RRF) for better ranking
• Dynamic Thresholds - Similarity thresholds adjust based on query length for better precision
• Improved Snippets - Search results highlight matching terms in context
• Extraction Validation - Reduces false positives in decision/mistake detection
• Query Expansion - Optional synonym expansion for broader recall (disabled by default)

Features

• Search conversations - Natural language search across your chat history
• Smart chunking - Long messages fully indexed without truncation
• Hybrid search - Combines vector + keyword search with RRF re-ranking
• Track decisions - Remember why you made technical choices
• Prevent mistakes - Learn from past errors
• Git integration - Link conversations to commits
• Cross-project search - Search across all your projects globally
• Project migration - Keep history when renaming/moving projects
• Semantic search - Uses Transformers.js embeddings (bundled, works offline)
• Working memory - Store and recall facts, decisions, and context across sessions
• Session handoff - Seamless context transfer between conversations
• Tag management - Organize memories, decisions, and patterns with tags
• Memory quality - Track confidence, importance, and verification status
• Database maintenance - Find duplicates, clean stale data, health reports

Installation

Node.js version

CCCMemory supports Node.js 20 or 22 LTS. Using other versions can break native modules (like better-sqlite3). If you switch Node versions, reinstall the package (or run npm rebuild better-sqlite3 in a local clone).

npm install -g cccmemory

Verify installation:

cccmemory --version

Configuration

For Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "cccmemory": {
      "command": "npx",
      "args": ["-y", "cccmemory"]
    }
  }
}

Then restart Claude Desktop.

For Claude Code

Edit ~/.claude.json (note: this file is in your home directory, not inside ~/.claude/):

{
  "mcpServers": {
    "cccmemory": {
      "command": "npx",
      "args": ["-y", "cccmemory"]
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "cccmemory": {
      "command": "cccmemory"
    }
  }
}

For Codex CLI

Codex stores MCP settings in ~/.codex/config.toml (shared by the CLI and the IDE extension).

Recommended (CLI):

codex mcp add cccmemory -- npx -y cccmemory

Manual config (~/.codex/config.toml):

[mcp_servers.cccmemory]
command = "npx"
args = ["-y", "cccmemory"]

If you installed globally, you can use:

[mcp_servers.cccmemory]
command = "cccmemory"

Open Codex and run /mcp in the TUI to verify the server is active.

Storage Paths

By default, CCCMemory uses a single database:

• ~/.cccmemory.db

If you want per-project isolation, set:

export CCCMEMORY_DB_MODE="per-project"

In per-project mode, CCCMemory stores:

• ~/.claude/projects/<project>/.cccmemory.db
• Fallback (restricted sandboxes): <project>/.cccmemory/.cccmemory.db

If your home directory is not writable (common in sandboxed Codex/Claude setups where ~/.claude and ~/.codex are locked), set an explicit writable path:

export CCCMEMORY_DB_PATH="/path/to/cccmemory.db"

For MCP configs, add these env vars in your server definition. CCCMemory stores the global project registry inside the same database (projects + project_sources tables).

Embedding Configuration (Optional)

The MCP uses Transformers.js by default for semantic search (bundled, works offline, no setup required).

Model download & cache behavior (Transformers.js):
On first use, @xenova/transformers downloads the model weights and caches them in its own default cache directory. CCCMemory does not manage or relocate that cache. Subsequent runs reuse the cached model and work fully offline.

To customize, create ~/.claude-memory-config.json:

{
  "embedding": {
    "provider": "transformers",
    "model": "Xenova/all-MiniLM-L6-v2",
    "dimensions": 384
  }
}

Alternative providers:

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh
ollama pull mxbai-embed-large
ollama serve

{
  "embedding": {
    "provider": "ollama",
    "model": "mxbai-embed-large",
    "dimensions": 1024
  }
}

{
  "embedding": {
    "provider": "openai",
    "model": "text-embedding-3-small",
    "dimensions": 1536
  }
}

Search Configuration (Optional)

Tune search behavior with environment variables:

MCP Tools

Indexing

Search

Context

Project Management

Working Memory

Session Handoff

Context Injection

Tag Management

Memory Quality

Maintenance

Session IDs

list_recent_sessions returns two identifiers:

• id: internal conversation id (use for scope="current" filters, handoffs, and documentation filters)
• session_id: external session id (Claude JSONL filename / Codex rollout id). Use for index_conversations and CLI index --session.

index_conversations accepts either, but external session_id is preferred.

CLI Usage

The package includes a standalone CLI:

# Interactive mode
cccmemory

# Single commands
cccmemory status
cccmemory index
cccmemory "search authentication"
cccmemory help

Supported Platforms

Why only Claude Code and Codex CLI today? CCCMemory indexes local session history from stable, parseable on-disk formats. Claude Code and Codex CLI both store full conversation logs locally with consistent schemas. Other tools either do not expose full local history, only support partial/manual saves, or do not provide a stable file format to parse reliably. Without deterministic local storage, there is nothing safe to index or resume.

Architecture

Single Database (default)
└── ~/.cccmemory.db
    ├── projects + project_aliases
    ├── project_sources (global index)
    └── conversations/messages/decisions/mistakes/...

Per-Project Databases (optional)
└── ~/.claude/projects/{project}/.cccmemory.db
    └── {project}/.cccmemory/.cccmemory.db (sandbox fallback)

Troubleshooting

Claude Desktop shows JSON parse errors

Upgrade to v1.7.3+:

npm update -g cccmemory

MCP not loading in Claude Code

1. Check config location is ~/.claude.json (not ~/.claude/config.json)
2. Verify JSON syntax is valid
3. Restart Claude Code

Embeddings not working

Check provider status:

cccmemory status

Default Transformers.js should work out of the box. If you opt into Ollama, ensure it's running (ollama serve).

License

MIT