Claude Conversation Memory MCP

CCCMemory MCP

一个MCP服务器，通过语义搜索、决策跟踪和跨项目搜索对对话历史进行索引，为克劳德提供长期记忆。

______________________________________________________________________

v2.0中的新增功能

2.0版本对搜索质量和准确性进行了重大改进：

• 智能分块 -长消息现在在句子边界处拆分，确保完整内容可搜索（以前截断为512个标记）
• 混合搜索 -使用互惠排名融合（RRF）将语义搜索与全文搜索相结合，以获得更好的排名
• 动态阈值 -相似性阈值根据查询长度进行调整，以提高精度
• 改进的片段 -搜索结果突出显示上下文中的匹配词
• 提取验证 -减少决策/错误检测中的误报
• 查询扩展 -可选同义词扩展以实现更广泛的召回（默认情况下禁用）

______________________________________________________________________

⚠️ Breaking Changes in v1.8.0 (click to expand)

此包已从重命名 claude-conversation-memory-mcp 到 cccmemory.

如果从旧软件包升级：

1. 卸载旧软件包： npm uninstall -g claude-conversation-memory-mcp
2. 安装新软件包： npm install -g cccmemory
3. 更新MCP配置以使用 cccmemory 命令
4. 数据库迁移是自动的(.claude-conversations-memory.db → .cccmemory.db)

______________________________________________________________________

特性

• 搜索对话 -在聊天记录中搜索自然语言
• 智能分块 -长消息完全索引，没有截断
• 混合搜索 -将矢量+关键字搜索与RRF重新排名相结合
• 跟踪决策 -记住你为什么做出技术选择
• 防止错误 -从过去的错误中吸取教训
• Git集成 -将对话链接到提交
• 跨项目搜索 -在全球范围内搜索您的所有项目
• 项目迁移 -重命名/移动项目时保留历史记录
• 语义搜索 -使用Transformers.js嵌入（捆绑，离线工作）
• 工作记忆 -跨会话存储和回忆事实、决策和上下文
• 会话切换 -对话之间无缝的上下文转换
• 标签管理 -使用标签组织记忆、决策和模式
• 内存质量 -跟踪信心、重要性和验证状态
• 数据库维护 -查找重复项、清理过时数据、运行状况报告

安装

Node.js版本

CCCMemory支持 Node.js 20或22 LTS.使用其他版本可能会破坏本机 模块（如 better-sqlite3).如果切换节点版本，请重新安装 包（或运行 npm rebuild better-sqlite3 在本地克隆中）。

npm install -g cccmemory

验证安装：

cccmemory --version

配置

适用于克劳德桌面

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

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

然后重新启动Claude Desktop。

克劳德代码

编辑 ~/.claude.json （注意：此文件位于您的主目录中，而不是内部 ~/.claude/):

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

或者，如果全局安装：

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

用于Codex CLI

Codex将MCP设置存储在 ~/.codex/config.toml （由CLI和IDE扩展共享）。

推荐（CLI）：

codex mcp add cccmemory -- npx -y cccmemory

手动配置(~/.codex/config.toml):

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

如果全局安装，则可以使用：

[mcp_servers.cccmemory]
command = "cccmemory"

打开Codex并运行 /mcp 在TUI中验证服务器是否处于活动状态。

存储路径

默认情况下，CCCMemory使用 单个数据库:

• ~/.cccmemory.db

如果要按项目隔离，请设置：

export CCCMEMORY_DB_MODE="per-project"

在每个项目模式下，CCCMemory存储：

• `~/.claude/projects/

/.cccmemory.db`

• 回退（受限沙盒）： `

/.cccmemory/.cccmemory.db`

如果您的主目录不可写（在沙盒Codex/Claude设置中很常见 ~/.claude 和 ~/.codex 被锁定），设置显式可写路径：

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

对于MCP配置，请在服务器定义中添加这些环境变量。CCCMemory存储 全球项目注册表 在同一数据库内 （项目+项目资源表）。

嵌入配置（可选）

MCP使用 Transformers.js 默认情况下用于语义搜索（捆绑，脱机工作，无需设置）。

模型下载和缓存行为（Transformers.js）：\ 在第一次使用时， @xenova/transformers 下载模型权重并将其缓存在自己的默认缓存目录中。CCCMemory不管理或重新定位该缓存。后续运行重用缓存的模型并完全脱机工作。

要自定义，请创建 ~/.claude-memory-config.json:

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

替代供应商：

Ollama (faster, requires Ollama running)

# 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
  }
}

OpenAI (requires API key)

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

集 OPENAI_API_KEY 环境变量。

搜索配置（可选）

使用环境变量调整搜索行为：

MCP工具

索引

搜索

上下文

项目管理

工作记忆

会话切换

上下文注入

标签管理

内存质量

维护

会话ID

list_recent_sessions 回报 两个标识符:

• id：内部对话id（用于 scope="current" 过滤器、切换和文档过滤器）
• session_id：外部会话id（Claude JSONL文件名/Codex卷展id）。用于 index_conversations 和CLI index --session.

index_conversations 要么接受，要么接受外部 session_id 是首选。

CLI使用情况

该软件包包括一个独立的CLI：

# Interactive mode
cccmemory

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

支持的平台

为什么今天只有Claude Code和Codex CLI？ CCCMemory从稳定的、可解析的磁盘格式中索引本地会话历史。Claude Code和Codex CLI都以一致的模式在本地存储完整的对话日志。其他工具要么不公开完整的本地历史记录，要么只支持部分/手动保存，要么不提供稳定的文件格式来可靠地解析。没有确定性的本地存储，就没有安全的索引或恢复。

建筑

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)

故障排除

Claude Desktop显示JSON解析错误

升级到v1.7.3+：

npm update -g cccmemory

Claude代码中未加载MCP

1. 检查配置位置是否 ~/.claude.json （不是 ~/.claude/config.json)
2. 验证JSON语法是否有效
3. 重新启动Claude代码

嵌入不起作用

检查提供商状态：

cccmemory status

默认Transformers.js应该可以开箱即用。如果你选择加入Ollama，请确保它正在运行(ollama serve).

许可证

麻省理工学院