CCCMemory MCP
一个MCP服务器,通过语义搜索、决策跟踪和跨项目搜索对对话历史进行索引,为克劳德提供长期记忆。
v2.0中的新增功能
2.0版本对搜索质量和准确性进行了重大改进:
- 智能分块 -长消息现在在句子边界处拆分,确保完整内容可搜索(以前截断为512个标记)
- 混合搜索 -使用互惠排名融合(RRF)将语义搜索与全文搜索相结合,以获得更好的排名
- 动态阈值 -相似性阈值根据查询长度进行调整,以提高精度
- 改进的片段 -搜索结果突出显示上下文中的匹配词
- 提取验证 -减少决策/错误检测中的误报
- 查询扩展 -可选同义词扩展以实现更广泛的召回(默认情况下禁用)
⚠️ Breaking Changes in v1.8.0 (click to expand)
此包已从重命名 claude-conversation-memory-mcp 到 cccmemory.
如果从旧软件包升级:
- 卸载旧软件包:
npm uninstall -g claude-conversation-memory-mcp - 安装新软件包:
npm install -g cccmemory - 更新MCP配置以使用
cccmemory命令 - 数据库迁移是自动的(
.claude-conversations-memory.db→.cccmemory.db)
特性
- 搜索对话 -在聊天记录中搜索自然语言
- 智能分块 -长消息完全索引,没有截断
- 混合搜索 -将矢量+关键字搜索与RRF重新排名相结合
- 跟踪决策 -记住你为什么做出技术选择
- 防止错误 -从过去的错误中吸取教训
- Git集成 -将对话链接到提交
- 跨项目搜索 -在全球范围内搜索您的所有项目
- 项目迁移 -重命名/移动项目时保留历史记录
- 语义搜索 -使用Transformers.js嵌入(捆绑,离线工作)
- 工作记忆 -跨会话存储和回忆事实、决策和上下文
- 会话切换 -对话之间无缝的上下文转换
- 标签管理 -使用标签组织记忆、决策和模式
- 内存质量 -跟踪信心、重要性和验证状态
- 数据库维护 -查找重复项、清理过时数据、运行状况报告
安装
Node.js版本
CCCMemory支持 Node.js 20或22 LTS.使用其他版本可能会破坏本机
模块(如 better-sqlite3).如果切换节点版本,请重新安装
包(或运行 npm rebuild better-sqlite3 在本地克隆中)。```bash
npm install -g cccmemory
验证安装:```bash
cccmemory --version
配置
适用于克劳德桌面
编辑 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)或 %APPDATA%\Claude\claude_desktop_config.json (Windows):```json
{
"mcpServers": {
"cccmemory": {
"command": "npx",
"args": ["-y", "cccmemory"]
}
}
}
然后重新启动Claude Desktop。
### 克劳德代码
编辑 `~/.claude.json` (注意:此文件位于您的主目录中,而不是内部 `~/.claude/`):```json
{
"mcpServers": {
"cccmemory": {
"command": "npx",
"args": ["-y", "cccmemory"]
}
}
}
或者,如果全局安装:```json
{
"mcpServers": {
"cccmemory": {
"command": "cccmemory"
}
}
}
### 用于Codex CLI
Codex将MCP设置存储在 `~/.codex/config.toml` (由CLI和IDE扩展共享)。
**推荐(CLI):**```bash
codex mcp add cccmemory -- npx -y cccmemory
手动配置(~/.codex/config.toml):```toml
[mcp_servers.cccmemory]
command = "npx"
args = ["-y", "cccmemory"]
如果全局安装,则可以使用:```toml
[mcp_servers.cccmemory]
command = "cccmemory"
打开Codex并运行 /mcp 在TUI中验证服务器是否处于活动状态。
存储路径
默认情况下,CCCMemory使用 单个数据库:
~/.cccmemory.db
如果要按项目隔离,请设置:```bash
export CCCMEMORY_DB_MODE="per-project"
在每个项目模式下,CCCMemory存储:
- `~/.claude/projects//.cccmemory.db`
- 回退(受限沙盒): `/.cccmemory/.cccmemory.db`
如果您的主目录不可写(在沙盒Codex/Claude设置中很常见
`~/.claude` 和 `~/.codex` 被锁定),设置显式可写路径:```bash
export CCCMEMORY_DB_PATH="/path/to/cccmemory.db"
对于MCP配置,请在服务器定义中添加这些环境变量。CCCMemory存储
全球项目注册表 在同一数据库内 (项目+项目资源表)。
嵌入配置(可选)
MCP使用 Transformers.js 默认情况下用于语义搜索(捆绑,脱机工作,无需设置)。
模型下载和缓存行为(Transformers.js):\
在第一次使用时, @xenova/transformers 下载模型权重并将其缓存在自己的默认缓存目录中。CCCMemory不管理或重新定位该缓存。后续运行重用缓存的模型并完全脱机工作。
要自定义,请创建 ~/.claude-memory-config.json:```json
{
"embedding": {
"provider": "transformers",
"model": "Xenova/all-MiniLM-L6-v2",
"dimensions": 384
}
}
**替代供应商:**
Ollama (faster, requires Ollama running)```bash
# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh
ollama pull mxbai-embed-large
ollama serve
配置:```json
{
"embedding": {
"provider": "ollama",
"model": "mxbai-embed-large",
"dimensions": 1024
}
}
OpenAI (requires API key)```json
{
"embedding": {
"provider": "openai",
"model": "text-embedding-3-small",
"dimensions": 1536
}
}
集 OPENAI_API_KEY 环境变量。
搜索配置(可选)
使用环境变量调整搜索行为:
| 变量 | 默认值 | 描述 |
|---|---|---|
CCCMEMORY_CHUNKING_ENABLED |
true |
为长消息启用智能分块 |
CCCMEMORY_CHUNK_SIZE |
450 |
目标块大小(以令牌为单位) |
CCCMEMORY_CHUNK_OVERLAP |
0.1 |
块之间的重叠(0-1) |
CCCMEMORY_RERANK_ENABLED |
true |
启用混合重新排序(向量+FTS) |
CCCMEMORY_RERANK_WEIGHT |
0.7 |
重新排序中的向量权重(FTS得到1个权重) |
CCCMEMORY_QUERY_EXPANSION |
false |
为查询启用同义词扩展 |
MCP工具
索引
| 工具 | 说明 |
|---|---|
index_conversations |
索引当前项目的对话 |
index_all_projects |
索引所有Claude Code+Codex项目 |
搜索
| 工具 | 说明 |
|---|---|
search_conversations |
在当前项目中搜索邮件 |
search_project_conversations |
在Claude Code+Codex中搜索项目 |
search_all_conversations |
在所有索引项目中搜索 |
get_decisions |
查找架构决策 |
get_all_decisions |
所有项目的决策 |
search_mistakes |
查找过去的错误和修复 |
search_all_mistakes |
所有项目中的错误 |
find_similar_sessions |
查找相关对话 |
上下文
| 工具 | 说明 |
|---|---|
check_before_modify |
编辑文件前获取上下文 |
get_file_evolution |
查看提交的文件历史记录 |
search_by_file |
查找与文件相关的所有上下文 |
list_recent_sessions |
列出最近的会议及其摘要 |
get_latest_session_summary |
总结最新会话(问题、操作、错误) |
recall_and_apply |
回忆当前任务的过去工作 |
get_requirements |
查找组件要求 |
get_tool_history |
查询工具使用历史 |
link_commits_to_conversations |
将git提交连接到会话 |
项目管理
| 工具 | 说明 |
|---|---|
discover_old_conversations |
从重命名的项目中查找文件夹 |
migrate_project |
迁移/合并对话历史记录 |
forget_by_topic |
按关键字删除对话 |
generate_documentation |
从本地代码扫描+对话生成文档 |
工作记忆
| 工具 | 说明 |
|---|---|
remember |
使用可选TTL存储事实、决策或上下文 |
recall |
按键检索特定内存 |
recall_relevant |
跨存储记忆的语义搜索 |
list_memory |
列出所有记忆,可选择按标签筛选 |
forget |
按键删除内存 |
会话切换
| 工具 | 说明 |
|---|---|
prepare_handoff |
为会话转换创建切换文档 |
resume_from_handoff |
从之前的移交中恢复工作 |
list_handoffs |
列出可用的移交文件 |
上下文注入
| 工具 | 说明 |
|---|---|
get_startup_context |
在对话开始时获取相关上下文 |
inject_relevant_context |
基于用户消息自动注入上下文 |
标签管理
| 工具 | 说明 |
|---|---|
list_tags |
列出所有带有使用统计信息的标签 |
search_by_tags |
按标签查找项目(记忆、决策、模式) |
rename_tag |
重命名所有项目的标签 |
merge_tags |
将多个标签合并为一个 |
delete_tag |
删除标记并取消链接所有项目 |
tag_item |
为项目添加标签 |
untag_item |
从项目中删除标签 |
内存质量
| 工具 | 说明 |
|---|---|
set_memory_confidence |
设定置信水平(不确定/可能/已确认/已验证) |
set_memory_importance |
设置重要性级别(低/正常/高/关键) |
pin_memory |
固定内存以防止清理 |
archive_memory |
使用可选原因存档内存 |
unarchive_memory |
恢复已存档的内存 |
search_memory_by_quality |
按信心/重要性搜索记忆 |
get_memory_stats |
按置信度/重要性获取内存统计数据 |
维护
| 工具 | 说明 |
|---|---|
get_storage_stats |
数据库大小和项目计数 |
find_stale_items |
查找最近未访问的项目 |
find_duplicates |
查找相似/重复项目 |
merge_duplicates |
合并重复项目 |
cleanup_stale |
存档或删除过时的项目 |
vacuum_database |
回收磁盘空间 |
cleanup_orphans |
删除孤立记录 |
get_health_report |
整体数据库健康检查 |
run_maintenance |
运行多个维护任务 |
get_maintenance_history |
查看过去的维护操作 |
会话ID
list_recent_sessions 回报 两个标识符:
id:内部对话id(用于scope="current"过滤器、切换和文档过滤器)session_id:外部会话id(Claude JSONL文件名/Codex卷展id)。用于index_conversations和CLIindex --session.
index_conversations 要么接受,要么接受外部 session_id 是首选。
CLI使用情况
该软件包包括一个独立的CLI:```bash
Interactive mode
cccmemory
Single commands
cccmemory status
cccmemory index
cccmemory "search authentication"
cccmemory help
## 支持的平台
|平台|状态|对话位置|
|----------|--------|----------------------|
|克劳德代码|✅ 支持| `~/.claude/projects/` |
|克劳德桌面|✅ 支持|(索引Claude代码历史)|
|食品法典|✅ 支持| `~/.codex/sessions/` |
**为什么今天只有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+:```bash
npm update -g cccmemory
### Claude代码中未加载MCP
1. 检查配置位置是否 `~/.claude.json` (不是 `~/.claude/config.json`)
1. 验证JSON语法是否有效
1. 重新启动Claude代码
### 嵌入不起作用
检查提供商状态:```bash
cccmemory status
默认Transformers.js应该可以开箱即用。如果你选择加入Ollama,请确保它正在运行(ollama serve).
许可证
麻省理工学院
