Claude Total Recall

克劳德全面召回

有没有告诉克劳德“就像我们昨天讨论的那样”才意识到。..它不知道吗？

全面回忆 为克劳德·科德提供了它缺失的内存。

1.压实会抹去细节

长时间的对话会受到语境的限制。当这种情况发生时，克劳德代码 紧凑型，总结之前的信息以腾出空间。一小时前那场精彩的调试会议？简化为“讨论的身份验证修复”。具体的错误代码、失败的方法、最终的解决方案：脱离上下文。

*但原始消息仍然存在于磁盘上。* 全面召回找到了他们。

2.会话是孤立的

每个Claude Code会话都会重新开始。昨天你花了一个小时解释你的项目架构。今天，克劳德不知道。你又开始解释了 UserService 会谈 AuthProvider 这验证了 TokenStore.

*每个会话都保存在本地。* 对所有这些内容进行全面召回搜索。

3.项目不共享知识

你总是使用 uv Python项目。你更喜欢 pnpm 超过 npm。您喜欢将测试放在源文件旁边，而不是放在单独的文件夹中。但克劳德每次在每个项目中都会问你。

*你的模式存在于过去的对话中。* Total Recall可以在您的所有项目中找到它们。

______________________________________________________________________

Total Recall索引每个Claude Code对话并提供语义搜索。 按以下方式查找讨论 *意义*不仅仅是关键词。问“我们是如何处理限速的？”它会找到相关的对话，即使你从未使用过这些确切的词语。

快速入门

# 1. Add the marketplace source (one-time)
/plugin marketplace add danilop/claude-total-recall

# 2. Install the plugin
/plugin install claude-total-recall@claude-total-recall

# 3. Restart Claude Code, then verify
/mcp    # Should list claude-total-recall

然后自然地问： *“我们上周是怎么修复这个bug的？”*

看 安装 对于替代方案。

______________________________________________________________________

运作原理

┌─────────────────────────────────────────────────────────────────────────┐
│                           Claude Code                                   │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐               │
│  │  Session 1   │    │  Session 2   │    │  Session N   │               │
│  │  messages    │    │  messages    │    │  messages    │               │
│  └──────┬───────┘    └──────┬───────┘    └──────┬───────┘               │
│         │                   │                   │                       │
│         └───────────────────┼───────────────────┘                       │
│                             ▼                                           │
│              ~/.claude/projects/
/                              │
│              ├── sessions-index.json                                    │
│              ├── .jsonl                                     │
│              └── /subagents/*.jsonl                         │
└─────────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                        Total Recall                                     │
│                                                                         │
│  ┌─────────┐    ┌──────────┐    ┌─────────┐    ┌────────────────────┐   │
│  │ loader  │───▶│ indexer  │───▶│  query  │───▶│  MCP server        │   │
│  │         │    │          │    │         │    │  (FastMCP)         │   │
│  │ Reads   │    │ Embeds   │    │ Cosine  │    │                    │   │
│  │ JSONL   │    │ text     │    │ search  │    │ search_project_    │   │
│  │ files   │    │ (384-d)  │    │         │    │ search_global_     │   │
│  └─────────┘    └────┬─────┘    └─────────┘    └────────────────────┘   │
│                      │                                    ▲             │
│                      ▼                                    │             │
│         ~/.cache/claude-total-recall/              MCP Protocol         │
│         └── embeddings.pkl                                │             │
└───────────────────────────────────────────────────────────┼─────────────┘
                                                            │
                                                            ▼
                                                  ┌──────────────────┐
                                                  │   Claude Code    │
                                                  │   (via plugin)   │
                                                  └──────────────────┘

数据：对话在哪里

Claude Code将所有对话存储在 ~/.claude/projects/每个项目都有自己的目录：

~/.claude/projects/
├── -Users-alice-myapp/              # /Users/alice/myapp
│   ├── sessions-index.json          # Session metadata
│   ├── abc123.jsonl                 # Main session messages
│   └── abc123/
│       └── subagents/
│           └── agent-def456.jsonl   # Subagent conversations
├── -Users-alice-other-project/
│   └── ...

路径逃逸：项目路径通过替换成为目录名 / 和 -所以 /Users/alice/myapp 成为 -Users-alice-myapp.

会话文件 (.jsonl)每行包含一个JSON对象：

{"type": "user", "uuid": "msg-123", "timestamp": 1706789012345, "message": {"role": "user", "content": "How do I fix this auth bug?"}}
{"type": "assistant", "uuid": "msg-124", "timestamp": 1706789015678, "message": {"role": "assistant", "content": [{"type": "text", "text": "Let me check the auth module..."}]}}

索引：快速搜索

首次搜索时，全面召回：

1. 负载 来自每个项目JSONL文件的所有消息
2. 嵌入 每条消息使用 全迷你LM-L6-v2 （384维向量，~80MB模型）
3. 缓存 嵌入到 ~/.cache/claude-total-recall/embeddings.pkl

后续搜索速度很快，因为：

• 指纹：计算所有的MD5 sessions-index.json 修改时间。只有在对话发生变化时才能重建。
• 增量更新：嵌入新消息；从缓存加载现有嵌入。
• 基于哈希的重复数据删除：每条消息文本都经过哈希处理。相同的文本=相同的嵌入（无需重新计算）。

并发安全：缓存使用文件锁定(fcntl.LOCK_EX)以及原子写入（临时文件+重命名）来处理多个克劳德代码实例。

搜索：找到重要的东西

搜索时：

1. 您的查询被嵌入到相同的384维空间中
2. 余弦相似度 找到最接近的匹配项（归一化向量的点积）
3. 高于阈值（默认值：0.2）的结果将与上下文一起返回

语义匹配 意味着“身份验证问题”可以找到关于“登录问题”或“JWT令牌错误”的讨论。不需要精确的关键字匹配。

上下文窗口 包括每场比赛前后的消息，这样你就可以看到完整的对话流程。

去重 合并重叠的窗口：如果消息5、6和7都匹配，你会得到一个带有上下文的结果（得分最高），而不是三个重叠的片段。

整合：MCP和技能

Total Recall通过以下方式与Claude Code集成 模型上下文协议（MCP）:

.mcp.json                           # Tells Claude Code how to start the server
  → uvx ... claude-total-recall     # Launches FastMCP server via uvx from GitHub
    → Exposes search_project_history, search_global_history tools

这 代理技能 (skills/conversation-recall/SKILL.md)教克劳德 *当* 要使用这些工具：

• “我们是如何修复这个bug的？”→ 触发器 search_project_history
• “我最喜欢的测试方法是什么？”→ 触发器 search_global_history
• 压实后→ 自动搜索以恢复摘要详细信息

特性

• 语义搜索：按含义查找，而不仅仅是关键字
• 上下文窗口：查看有关比赛的完整对话
• 项目筛选：搜索当前项目或所有项目
• 增量索引：仅处理新对话
• 压实恢复：检索总结上下文时丢失的详细信息
• 代理技能：相关问题自动触发

安装

先决条件

• 克劳德代码
• 紫外线 包管理器

选项1：从GitHub安装（推荐）

# In Claude Code, add the marketplace source
/plugin marketplace add danilop/claude-total-recall

# Install the plugin
/plugin install claude-total-recall@claude-total-recall

重新启动Claude代码 安装后。MCP服务器仅在启动时加载。

MCP服务器通过以下方式运行 uvx 直接从GitHub，因此依赖关系是自动管理的。

选项2：从本地目录安装

发展：

git clone https://github.com/danilop/claude-total-recall.git
cd claude-total-recall

然后用插件启动Claude Code：

claude --plugin-dir /path/to/claude-total-recall

非永久你必须通过 --plugin-dir 每一次。

更新中

MCP服务器会自动使用GitHub上的最新版本。要更新技能文件，请执行以下操作：

cd ~/.claude/plugins/marketplaces/claude-total-recall
git pull

要强制刷新MCP服务器缓存，请执行以下操作：

uvx --refresh --from git+https://github.com/danilop/claude-total-recall claude-total-recall

重新启动Claude代码 更新后。

验证安装

在克劳德代码中：

• /mcp 应列出 claude-total-recall
• /skills 应列出 conversation-recall

用法

自然语言（通过技能）

自然地问。该技能会自动触发：

"How did we fix that auth bug?"
"What did we discuss about the database schema?"
"Find our React component discussions"
"What's my usual approach to error handling?"

MCP工具

恢复压缩的上下文

当Claude Code压缩对话时（约95%的上下文或通过 /compact)，细节得到总结。全面召回检索原件：

User: "Continue with the auth approach we discussed"
Claude: [searches for "auth approach implementation" to recover details]

参数

日期筛选示例

# Messages from a specific day
search_project_history(query="auth bug", after="2025-01-15", before="2025-01-16")

# Messages from the past week
search_project_history(query="refactoring", after="2025-01-25")

# Messages in January
search_project_history(query="database", after="2025-01-01", before="2025-02-01")

响应结构

{
  "results": [
    {
      "matched_message": {
        "role": "assistant",
        "content": "To fix the authentication bug...",
        "timestamp": "2025-01-15T10:30:00Z",
        "project": "/Users/dev/myproject",
        "session_id": "abc123",
        "uuid": "msg-456"
      },
      "score": 0.8542,
      "context": [
        {"role": "user", "content": "How do I fix this auth bug?", "timestamp": "...", "is_match": false},
        {"role": "assistant", "content": "To fix the authentication bug...", "timestamp": "...", "is_match": true}
      ]
    }
  ],
  "query": "authentication bug fix",
  "total_matches": 25,
  "offset": 0,
  "has_more": true,
  "excluded_sessions": 0,
  "hint": "Showing 1-10 of 25 matches. To retrieve more, use offset: 10. Or try different search terms."
}

这 hint 字段提供了下一步的指导：

• 当有更多结果可用时，它会显示 offset 用于下一页的值
• 当没有找到结果时，它建议尝试不同的搜索词
• 始终包括显示的范围（例如，“显示25个中的1-10”）

分页

# First page
search_project_history(query="auth bug", max_results=10, offset=0)

# Next page
search_project_history(query="auth bug", max_results=10, offset=10)

内存管理

内存索引大小的总召回限制，以防止内存过度使用。默认情况下，它使用1/3的物理RAM。当达到限制时，最旧的会话将被排除在索引之外（最新的会话将保留）。磁盘上的所有对话文件都将保留。

当会话被排除时 excluded_sessions 搜索响应中的字段指示有多少会话未被索引。还会记录一个警告。

配置

示例：

# Limit to 256 MB
export TOTAL_RECALL_MEMORY_LIMIT_MB=256

# Disable limit (index all sessions)
export TOTAL_RECALL_NO_MEMORY_LIMIT=1

测试

没有克劳德代码

# Test server starts
uv run claude-total-recall
# Ctrl+C to exit

# Test search directly
uv run python -c "
from claude_total_recall.server import search_global_history
result = search_global_history(query='bug fix', max_results=3)
print(f'Found {result[\"total_matches\"]} matches')
"

克劳德密码

1. 加载插件
2. 跑 /mcp 验证
3. 询问：“搜索我之前的对话以获取身份验证”

项目结构

claude-total-recall/
├── .claude-plugin/
│   ├── plugin.json              # Plugin manifest
│   └── marketplace.json         # Distribution config
├── skills/
│   └── conversation-recall/
│       └── SKILL.md             # When to trigger searches
├── .mcp.json                    # MCP server config
├── src/claude_total_recall/
│   ├── server.py                # FastMCP server, tool definitions
│   ├── query.py                 # Search engine, deduplication
│   ├── indexer.py               # Embedding, caching, fingerprinting
│   ├── loader.py                # JSONL parsing, session loading
│   └── models.py                # Pydantic data models
├── pyproject.toml
└── LICENSE

技术细节

许可证

MIT许可证