STARWARCLOUD STARWAR.AI
返回市场
克劳德对话记忆MCP

克劳德对话记忆MCP

作者：xiaolai11 星标更新：2025-11-17
安装使用来源：spider==github.com

项目介绍

Claude Conversation Memory

这是一个Model Context Protocol (MCP)服务器，通过索引来自Claude Code CLI和Codex的对话历史记录，提供语义搜索、决策跟踪、错误预防以及全局跨项目搜索功能，从而赋予AI助手长期记忆。

💡 功能概述

核心记忆特性

  • 记住过去的对话 - 使用自然语言搜索聊天历史
  • 跟踪决策 - 不会忘记为什么做出技术选择
  • 预防错误 - 从过去的错误中学习并避免重复
  • 链接到git提交 - 将对话与代码更改连接起来
  • 分析文件历史 - 查看带有上下文的文件完整演变过程
  • 上下文转移 - 回忆过去的工作并将其应用于当前任务（“记住X，现在基于此做Y”）

全局跨项目搜索 ✨ 新功能

  • 跨所有项目搜索 - 在整个工作历史中查找对话
  • 双源支持 - 索引来自Claude Code CLI和Codex
  • 统一界面 - 一次查询即可搜索任何来源的对话
  • 项目过滤 - 按来源类型（claude-code、codex或全部）过滤
  • 混合架构 - 每个项目数据库 + 全局注册表以实现快速、隔离访问

项目管理

  • 迁移对话历史 - 重命名或移动项目时保留历史
  • 有选择地遗忘 - 按主题/关键词删除对话，并自动备份
  • 跨项目洞察 - 发现所有工作中所做的决策和错误

🎯 双源支持

此MCP服务器支持两个AI编码助手平台：

✅ Claude Code CLI

✅ Codex

  • 完全集成：v1.5.0新功能
  • 存储位置：~/.codex/sessions/
  • 日期分层：会话按YYYY/MM/DD/组织
  • 专用数据库：单独的数据库位于~/.codex/.codex-conversations-memory.db

❌ 不支持

  • Claude Desktop（不同的对话格式）
  • Claude Web（无本地存储）
  • 其他Claude集成

🌐 全局跨项目搜索

混合架构使强大的跨项目搜索能力成为可能：

工作原理

┌─────────────────────────────────────────────────────────────┐
│                    全局架构                                  │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ~/.claude/.claude-global-index.db (中央注册表)            │
│  ┌─────────────────────────────────────────────────────┐    │
│  │ 跟踪所有已索引的项目：                                │    │
│  │ • 项目路径和来源类型                                  │    │
│  │ • 数据库位置                                          │    │
│  │ • 汇总统计信息                                        │    │
│  │ • 最后索引的时间戳                                    │    │
│  └─────────────────────────────────────────────────────┘    │
│                          │                                    │
│            ┌─────────────┼─────────────┐                     │
│            ▼             ▼             ▼                     │
│   ┌────────────┐ ┌────────────┐ ┌────────────┐             │
│   │ 项目A      │ │ 项目B      │ │ Codex      │             │
│   │ 数据库     │ │ 数据库     │ │ 数据库     │             │
│   │            │ │            │ │            │             │
│   │ • 对话     │ │ • 对话     │ │ • 会话     │             │
│   │ • 消息     │ │ • 消息     │ │ • 消息     │             │
│   │ • 决策     │ │ • 决策     │ │ • 工具     │             │
│   │ • 错误     │ │ • 错误     │ │ • 提交     │             │
│   └────────────┘ └────────────┘ └────────────┘             │
│                                                               │
└─────────────────────────────────────────────────────────────┘

优点

隔离：每个项目有自己的数据库 - 避免交叉污染 速度：直接数据库访问 - 没有中心瓶颈 隐私：项目保持分离直到您明确进行全局搜索 可扩展性：添加无限项目而不会影响性能

全局搜索工具

四个新的MCP工具支持跨项目搜索：

  1. index_all_projects - 一次性索引所有Claude Code项目和Codex
  2. search_all_conversations - 在所有已索引项目中搜索消息
  3. get_all_decisions - 从任何项目中找到决策（即将推出）
  4. search_all_mistakes - 从所有工作中学习错误（即将推出）

📦 安装

前提条件

必需：

  1. Node.js：版本18或更高
  2. Claude Code CLI 或 Codex：至少一个AI助手平台
  3. sqlite-vec扩展：自动加载（捆绑在包中）

推荐用于更好的语义搜索： 4. Ollama：用于高质量本地嵌入

# macOS/Linux
curl -fsSL https://ollama.com/install.sh | sh

# 或从以下网址下载：https://ollama.com
  1. 默认嵌入模型（如果使用Ollama）： 
    # 拉取推荐模型
ollama pull mxbai-embed-large

# 启动Ollama服务
ollama serve

注意：如果没有Ollama，MCP将自动回退到Transformers.js（较慢但无需设置即可离线工作）。

安装MCP服务器

npm install -g claude-conversation-memory-mcp

🎉 自动配置：全局安装将自动在Claude Code的~/.claude.json文件中配置MCP服务器。完成时您会看到成功消息！

手动配置（如有需要）：如果自动配置不起作用，请参阅下方的配置Claude Code CLI部分。

发现可用模型： 安装后，您可以查看所有可用的嵌入模型及其维度：

  • 运行CLI：claude-conversation-memory-mcp
  • 输入：config 查看按提供商组织的所有可用模型
  • 或检查示例配置文件：.claude-memory-config.example.jsonc

配置Claude Code CLI

MCP配置文件优先级：

Claude Code按以下顺序检查MCP服务器配置（从最高到最低优先级）：

  1. .mcp.json - 项目级别（在项目根目录下）- 最高优先级
  2. ~/.claude.json - 用户级别全局（在用户主目录下）- 较低优先级

注意：文件~/.claude/settings.json不用于MCP服务器配置（仅用于权限）。始终使用~/.claude.json进行全局MCP服务器配置。

选项1：全局配置（推荐）

创建或编辑~/.claude.json：

{
  "mcpServers": {
    "conversation-memory": {
      "command": "claude-conversation-memory-mcp"
    }
  }
}

选项2：项目级别配置

在项目根目录下创建.mcp.json：

{
  "mcpServers": {
    "conversation-memory": {
      "command": "claude-conversation-memory-mcp"
    }
  }
}

替代方案：无需全局安装使用npx

{
  "mcpServers": {
    "conversation-memory": {
      "command": "npx",
      "args": ["-y", "claude-conversation-memory-mcp"]
    }
  }
}

验证安装

启动Claude Code CLI并询问：

"索引我的对话历史"

如果您看到类似“索引了3个对话，包含1247条消息”的响应，说明它正在工作！

重要提示：更新后的重启

当您升级到新版本时，必须重启Claude Code CLI以重新加载MCP服务器：

  1. 完全退出Claude Code CLI
  2. 再次启动它
  3. 新版本将被加载

原因：Claude Code缓存MCP服务器。如果不重启，即使您已经全局升级了npm包，它仍将继续使用旧的缓存版本。

快速检查：重启后，您可以验证版本：

claude-conversation-memory-mcp --version

🖥️ 独立CLI / REPL模式

除了MCP服务器外，该包还包括一个强大的独立CLI，可以直接从终端管理您的对话记忆。

三种操作模式

1. 交互式REPL模式（默认）

claude-conversation-memory-mcp
# 启动具有40多个命令的交互式shell

2. 单一命令模式

claude-conversation-memory-mcp status
claude-conversation-memory-mcp "搜索认证"
claude-conversation-memory-mcp 错误 --限制 5

3. MCP服务器模式（由Claude Code CLI使用）

claude-conversation-memory-mcp --server
# 或通过Claude Code CLI自动通过stdio

快速CLI示例

# 查看数据库状态
claude-conversation-memory-mcp status

# 索引对话（当前项目）
claude-conversation-memory-mcp 索引 --包含-mcp

# 索引所有项目 + Codex（新功能）
claude-conversation-memory-mcp 索引所有 --codex --claude-code

# 搜索主题
claude-conversation-memory-mcp "搜索数据库迁移" --限制 3

# 跨所有项目搜索（新功能）
claude-conversation-memory-mcp "搜索所有认证" --限制 10

# 查找过去的错误
claude-conversation-memory-mcp 错误 "异步" --类型 逻辑错误

# 编辑前检查文件上下文
claude-conversation-memory-mcp 检查 src/auth.ts

# 配置嵌入模型
claude-conversation-memory-mcp 配置
claude-conversation-memory-mcp 设置 模型 mxbai-embed-large
claude-conversation-memory-mcp 设置 维度 1024

# 查看帮助
claude-conversation-memory-mcp 帮助
claude-conversation-memory-mcp "帮助搜索"

配置管理

CLI包括内置命令来管理嵌入模型和维度：

# 查看当前配置
claude-conversation-memory-mcp 配置

# 切换到Ollama并使用mxbai-embed-large（1024维）
claude-conversation-memory-mcp 设置 提供者 ollama
claude-conversation-memory-mcp 设置 模型 mxbai-embed-large
claude-conversation-memory-mcp 设置 维度 1024

# 切换到Transformers.js（离线，无需设置）
claude-conversation-memory-mcp 设置 提供者 transformers
claude-conversation-memory-mcp 设置 模型 Xenova/all-MiniLM-L6-v2
claude-conversation-memory-mcp 设置 维度 384

# 获取特定配置值
claude-conversation-memory-mcp 获取 提供者

可用命令

  • 📥 索引：索引，重新索引，索引所有（新功能）
  • 🔍 搜索：搜索，搜索所有（新功能），决策，错误，相似
  • 📋 文件：检查，历史
  • 🔗 Git：提交
  • 📝 其他：需求，工具，文档
  • ℹ️ 信息：状态，版本，帮助
  • ⚙️ 配置：配置，获取，设置
  • 🧹 维护：清理，重置

👉 请参阅完整的CLI指南了解所有命令、示例和工作流程

🎯 使用示例

第一次设置 - 单个项目

您："索引这个项目的对话历史"

Claude：我将索引这个项目的所有对话...
✓ 索引了5个对话，包含2,341条消息
✓ 开启语义搜索（生成嵌入）

第一次设置 - 所有项目 + Codex ✨ 新功能

您："索引我所有的项目，包括Codex对话"

Claude：我将索引来自Claude Code和Codex的所有项目...
✓ 索引了3个Claude Code项目（47个对话）
✓ 索引了Codex会话（128个对话）
✓ 在~/.claude/.claude-global-index.db创建全局索引
✓ 总计：4个项目中的175个对话

跨所有项目搜索 ✨ 新功能

您："搜索我关于认证的所有对话"

Claude：正在跨4个已索引项目搜索...
找到12个结果：
• 项目：my-api（claude-code）- 5个对话
• 项目：mobile-app（claude-code）- 3个对话
• 项目：Codex（codex）- 4个对话
[返回相关消息及项目上下文]

当前项目内搜索

您："关于我们讨论过的认证系统是什么？"

Claude：让我搜索我们在这个项目中的对话历史...
[返回相关消息及时间戳]

修改文件前

您："在我修改database.ts之前，我应该知道什么？"

Claude：让我检查database.ts的上下文...
[显示最近更改、相关决策和过去的错误]

跟踪决策

您："为什么我们选择了SQLite而不是PostgreSQL？"

Claude：让我检查我们的决策历史...
[返回决策及其理由和考虑的替代方案]

从错误中学习

您："我们在以前是否遇到过异步/等待的问题？"

Claude：让我搜索过去的错误...
[显示之前的错误及其修复方法]

跨项目查找相关工作 ✨ 新功能

您："搜索所有项目中类似的API端点实现"

Claude：正在跨所有已索引项目搜索...
找到类似的工作：
• 项目A：REST API设计模式
• 项目B：GraphQL端点结构
• Codex：API版本化方法
[返回来自多个项目的相关会话]

查看文件历史

您："展示auth.ts是如何随时间演化的"

Claude：让我追踪文件的演化...
[显示完整的时序图，包括对话、提交和决策]

回忆并应用上下文

您："回忆我们如何实现认证，现在使用相同的模式添加OAuth支持"

Claude：让我回忆认证实现的上下文...
[返回相关的对话、决策、错误、文件更改和提交]
[提供将此上下文应用于OAuth实现的建议]

更多示例：

  • "记住我们在parser.ts中修复的bug，检查lexer.ts中是否存在类似问题"
  • "回忆所有关于数据库模式的决策，现在设计迁移策略"
  • "查找我们在异步/等待方面犯过的错误，在这个新的异步函数中避免它们"
  • "搜索我在所有项目中如何处理错误边界" ✨ 新功能

🔧 高级用法

全局索引选项 ✨ 新功能

索引所有项目

您："索引我来自Claude Code和Codex的所有项目"

# 带选项：
您："索引所有项目，包含自定义路径/.codex的Codex，排除MCP对话"

选项：

  • include_codex（默认：true） - 索引Codex会话
  • include_claude_code（默认：true） - 索引Claude Code项目
  • codex_path - 自定义Codex位置（默认：~/.codex）
  • claude_projects_path - 自定义Claude Code项目位置（默认：~/.claude/projects）

按来源过滤全局搜索

您："只搜索Claude Code项目中的认证"
# source_type: "claude-code"

您："只搜索Codex会话中的数据库设计"
# source_type: "codex"

您："搜索所有来源中的错误处理"
# source_type: "all"（默认）

索引特定会话

您："索引会话a1172af3-ca62-41be-9b90-701cef39daae的对话"

排除MCP对话

默认情况下，关于MCP本身的对话会被排除以防止自我引用循环。要包含它们：

您："索引所有对话，包括MCP对话"

索引选项

在索引对话时，几个选项控制存储的内容：

包含思考块

默认：false（思考块被排除）

思考块包含Claude的内部推理过程。它们可以非常大（数据量多3-5倍），通常不需要用于搜索。

# 默认行为（推荐）
您："索引对话"
# 思考块被排除

# 包含思考块（显著增加数据库大小）
您："索引包含思考块的对话"

何时启用：

  • ✅ 您想要搜索Claude的推理过程
  • ✅ 您正在分析决策