CCCMemory MCP

CCCMemory MCP

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)

---

<details> <summary><strong>⚠️ Breaking Changes in v1.8.0</strong> (click to expand)</summary>

This package was renamed from claude-conversation-memory-mcp to cccmemory.

If upgrading from the old package:

1. Uninstall old package: npm uninstall -g claude-conversation-memory-mcp
2. Install new package: npm install -g cccmemory
3. Update MCP config to use cccmemory command
4. Database migration is automatic (.claude-conversations-memory.db → .cccmemory.db)

</details>

---

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): ``bash codex mcp add cccmemory -- npx -y cccmemory ``

Manual config (~/.codex/config.toml): ``toml [mcp_servers.cccmemory] command = "npx" args = ["-y", "cccmemory"] ``

If you installed globally, you can use: ``toml [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:

<details> <summary>Ollama (faster, requires Ollama running)</summary>

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

Config: ``json { "embedding": { "provider": "ollama", "model": "mxbai-embed-large", "dimensions": 1024 } } `` </details>

<details> <summary>OpenAI (requires API key)</summary>

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

Set OPENAI_API_KEY environment variable. </details>

Search Configuration (Optional)

Tune search behavior with environment variables:

| Variable | Default | Description | |----------|---------|-------------| | CCCMEMORY_CHUNKING_ENABLED | true | Enable smart chunking for long messages | | CCCMEMORY_CHUNK_SIZE | 450 | Target chunk size in tokens | | CCCMEMORY_CHUNK_OVERLAP | 0.1 | Overlap between chunks (0-1) | | CCCMEMORY_RERANK_ENABLED | true | Enable hybrid re-ranking (vector + FTS) | | CCCMEMORY_RERANK_WEIGHT | 0.7 | Vector weight in re-ranking (FTS gets 1-weight) | | CCCMEMORY_QUERY_EXPANSION | false | Enable synonym expansion for queries |

MCP Tools

Indexing

| Tool | Description | |------|-------------| | index_conversations | Index current project's conversations | | index_all_projects | Index all Claude Code + Codex projects |

Search

| Tool | Description | |------|-------------| | search_conversations | Search messages in current project | | search_project_conversations | Search a project across Claude Code + Codex | | search_all_conversations | Search across all indexed projects | | get_decisions | Find architectural decisions | | get_all_decisions | Decisions across all projects | | search_mistakes | Find past errors and fixes | | search_all_mistakes | Mistakes across all projects | | find_similar_sessions | Find related conversations |

Context

| Tool | Description | |------|-------------| | check_before_modify | Get context before editing a file | | get_file_evolution | See file history with commits | | search_by_file | Find all context related to a file | | list_recent_sessions | List recent sessions with summaries | | get_latest_session_summary | Summarize the latest session (problem, actions, errors) | | recall_and_apply | Recall past work for current task | | get_requirements | Look up component requirements | | get_tool_history | Query tool usage history | | link_commits_to_conversations | Connect git commits to sessions |

Project Management

| Tool | Description | |------|-------------| | discover_old_conversations | Find folders from renamed projects | | migrate_project | Migrate/merge conversation history | | forget_by_topic | Delete conversations by keyword | | generate_documentation | Generate docs from local code scan + conversations |

Working Memory

| Tool | Description | |------|-------------| | remember | Store a fact, decision, or context with optional TTL | | recall | Retrieve a specific memory by key | | recall_relevant | Semantic search across stored memories | | list_memory | List all memories, optionally filtered by tags | | forget | Remove a memory by key |

Session Handoff

| Tool | Description | |------|-------------| | prepare_handoff | Create handoff document for session transition | | resume_from_handoff | Resume work from a previous handoff | | list_handoffs | List available handoff documents |

Context Injection

| Tool | Description | |------|-------------| | get_startup_context | Get relevant context at conversation start | | inject_relevant_context | Auto-inject context based on user message |

Tag Management

| Tool | Description | |------|-------------| | list_tags | List all tags with usage statistics | | search_by_tags | Find items by tag (memories, decisions, patterns) | | rename_tag | Rename a tag across all items | | merge_tags | Merge multiple tags into one | | delete_tag | Delete a tag and unlink all items | | tag_item | Add tags to an item | | untag_item | Remove tags from an item |

Memory Quality

| Tool | Description | |------|-------------| | set_memory_confidence | Set confidence level (uncertain/likely/confirmed/verified) | | set_memory_importance | Set importance level (low/normal/high/critical) | | pin_memory | Pin a memory to prevent cleanup | | archive_memory | Archive a memory with optional reason | | unarchive_memory | Restore an archived memory | | search_memory_by_quality | Search memories by confidence/importance | | get_memory_stats | Get memory statistics by confidence/importance |

Maintenance

| Tool | Description | |------|-------------| | get_storage_stats | Database size and item counts | | find_stale_items | Find items not accessed recently | | find_duplicates | Find similar/duplicate items | | merge_duplicates | Merge duplicate items | | cleanup_stale | Archive or delete stale items | | vacuum_database | Reclaim disk space | | cleanup_orphans | Remove orphaned records | | get_health_report | Overall database health check | | run_maintenance | Run multiple maintenance tasks | | get_maintenance_history | View past maintenance operations |

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

| Platform | Status | Conversation Location | |----------|--------|----------------------| | Claude Code | ✅ Supported | ~/.claude/projects/ | | Claude Desktop | ✅ Supported | (indexes Claude Code history) | | Codex | ✅ Supported | ~/.codex/sessions/ |

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+: ``bash 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: ``bash cccmemory status ``

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

License

MIT