1. 项目概述一个为AI开发者打造的会话历史管理利器如果你和我一样日常重度依赖 Claude Code 和 Cursor 这两个AI编程助手那你一定遇到过这个痛点上周那个解决了某个诡异docker-compose网络问题的对话或者昨天那个生成了完美React组件逻辑的会话现在怎么也想不起来具体是哪个了。在项目文件夹里翻找那些散落的.jsonl或.txt文件无异于大海捞针。chat-history这个用 Rust 编写的高性能命令行工具就是来解决这个问题的。它不是一个简单的文件查看器而是一个专为开发者设计的、具备智能搜索和上下文管理能力的“会话记忆中枢”。简单来说chat-history能让你像使用grep搜索代码一样闪电般地搜索你与 Claude 或 Cursor 的所有对话历史。无论是通过会话摘要、第一条提示还是深入对话内容本身它都能在亚秒级内返回结果。更重要的是它原生支持为 Claude Code 和 Cursor 的 AI Agent 安装“技能”Skill让 Agent 在与你对话时能自动查询相关历史形成真正的“记忆延续”。对于追求效率、厌恶信息碎片化的开发者而言这无疑是一个能将 AI 助手价值最大化的基础工具。2. 核心设计思路为什么是 Rust 双层搜索架构2.1 技术选型Rust 带来的性能与可靠性优势这个项目选择用 Rust 实现绝非偶然。处理可能包含数万条消息、总大小数 GB 的会话历史文件性能是首要考量。Rust 的零成本抽象和内存安全特性在这里发挥了关键作用。极致性能会话索引的构建和搜索操作涉及大量的字符串处理、JSON 解析和并行计算。Rust 的编译时优化和高效的内存管理确保了即使在首次扫描全量历史文件时也能保持流畅。在实际测试中对包含上千个会话的索引进行关键词搜索响应时间稳定在 100 毫秒以内这种“无感”的搜索体验是脚本语言如 Python难以企及的。并发安全工具利用rayon库进行数据并行处理在深度搜索--deep时需要同时解析多个 transcript 文件。Rust 的所有权系统和rayon的安全抽象使得编写高效且绝不会出现数据竞争的并行代码变得非常简单这对于保证工具稳定性至关重要。单文件部署通过cargo install编译出的二进制文件是静态链接的可以轻松复制到任何同类系统上运行无需担心运行时环境或依赖库版本问题大大简化了分发和使用。注意虽然安装需要 Rust 工具链但一旦通过cargo install完成安装用户使用的就是一个独立的、高性能的可执行文件与复杂的 Rust 开发环境完全解耦。2.2 架构解析索引搜索与深度搜索的双层设计chat-history最精妙的设计在于其双层搜索架构这直接借鉴了现代搜索引擎的思想在速度与完整性之间取得了完美平衡。第一层索引搜索Index Search这是默认的搜索模式速度极快亚秒级。它并不直接打开庞大的 transcript 文件而是读取一个由 Claude Code/Cursor 自动生成的轻量级sessions-index.json文件。这个索引文件通常只包含会话的元数据会话摘要Summary第一条用户提示First Prompt关联的 Git 分支Branch项目路径Project Path时间戳和基础统计信息搜索时工具会对这些字段进行加权匹配例如摘要匹配的权重是分支匹配的3倍并结合时间衰减因子今天的会话权重更高进行综合评分。只有当索引搜索的结果评分低于阈值例如 5.0时系统才会自动“降级”到第二层搜索。这种设计意味着对于大多数通过摘要或核心提示就能定位的会话搜索是瞬间完成的。第二层深度搜索Deep Search当使用--deep参数或索引搜索未找到满意结果时工具会启动深度搜索。这会动用rayon并行池同时打开并解析指定的原始 transcript 文件.jsonl或纯文本深入每一条助理和用户的消息内容中进行查找。深度搜索的评分算法复杂得多它融合了多个开源项目的策略核心术语精确匹配如果查询词是“docker”、“react”这类明确的框架/工具名匹配项会获得很高基础分10分。词边界与子串匹配在完整单词边界上匹配得2分作为子串匹配则得1分。这保证了搜索“auth”能有效命中“authentication”。语义增强这是智能化的关键。当查询包含“error”时对话中实际出现错误堆栈或日志的部分会被额外加权3倍。当查询包含“fix”、“solve”时那些包含解决方案、修正代码的段落会获得更高权重2.8倍。这使搜索结果更贴合开发者的真实意图——找错误时优先看到报错上下文找方案时优先看到解决代码。去重与限流为了避免同一个会话中大量相似内容淹没结果算法会对内容进行归一化签名并限制每个会话最多只贡献3个最佳匹配片段。这种“索引先行深度兜底”的策略确保了 90% 的日常查询都能得到即时响应同时在需要深挖时又能提供全面、相关的结果。3. 从安装到上手完整实操指南3.1 安装与环境准备安装过程非常 straightforward前提是你的系统已经安装了 Rust 工具链。如果你还没有安装 Rust强烈建议通过官方rustup脚本进行安装它能帮你管理多个 Rust 版本。# 1. 安装 Rust (如果尚未安装) curl --proto https --tlsv1.2 -sSf https://sh.rustup.rs | sh # 安装完成后按照提示执行 source 命令或重启终端使 cargo 命令生效。 # 2. 通过 cargo 从 crates.io 安装 chat-history cargo install chat-history安装成功后chat-history以及它的短别名ch会被放置在~/.cargo/bin/目录下。请确保该目录已加入你的系统PATH环境变量中rustup通常会自动配置。从源码构建如果你想体验最新开发版或进行二次开发可以克隆仓库并本地安装。git clone https://github.com/ay-bh/chat-history.git cd chat-history cargo install --path . # 这会在本地编译并安装3.2 核心命令详解与使用场景安装完成后你就可以开始探索你的对话历史了。下面我们拆解每个核心命令并附上真实的使用场景。3.2.1 列出会话 (list 默认命令)这是最基础的命令用于浏览所有会话。直接运行chat-history或ch会按时间倒序列出所有会话。# 基础列表 ch # 实用过滤组合查看昨天所有会话并按日期分组显示 ch --from yesterday -s # 输出示例 # 2024-05-14 # [a1b2c3d4] 10:32 Fix Docker network conflict in compose file # [e5f6g7h8] 14:15 Implement user auth middleware with JWT # 2024-05-13 # [i9j0k1l2] 09:18 Debug React infinite re-render loop-s(--group-by-day) 参数让输出按日期分组视觉上更清晰特别适合回顾近期工作。--from和--to支持自然语言日期如“3 days ago”,“last monday”和标准日期格式过滤非常灵活。-k(--keyword) 可以在列表时就进行关键词过滤-v会同时显示会话的完整ID和文件路径便于后续脚本处理。3.2.2 智能搜索 (search)这是工具的精华所在。搜索时务必理解索引搜索和深度搜索的区别。# 场景1快速回忆——“我之前处理过身份验证的问题” ch search “auth” # 这会快速扫描索引摘要、首条提示可能返回标题或首条提示包含“auth”、“authentication”的会话。 # 场景2深度挖掘——“我记得在某个对话的中间部分讨论过‘递归组件的性能优化’” ch search “递归 组件 性能” --deep # 使用 --deep 强制搜索全部对话内容。对于中文或复杂技术短语深度搜索更有效。 # 场景3精准定位——“找上周在‘feature/user-profile’分支上关于‘头像上传’的对话” ch search “头像上传” --branch feature/user-profile --from “last week” # 结合分支和时间过滤器能极大缩小范围。 # 场景4排查问题——“最近遇到的构建错误是什么” ch search “error: failed to compile” --scope errors --timeframe week # --scope errors 会启用错误模式增强优先高亮对话中的错误堆栈和日志部分。 # --timeframe week 将搜索范围限制在过去一周。3.2.3 查看会话详情 (inspect与view)搜索到目标会话ID如[a1b2c3d4]后下一步就是深入查看。inspect命令给你一个高度概括的“摘要页”非常适合快速回顾。ch inspect a1b2c3d4 # 输出会包括 # - 关键决策 (Key Decisions) # - 使用的工具 (Tools Used) # - 涉及的文件 (Files Touched) # - 使用的模型和令牌统计 # 这让你在几秒钟内就能重拾会话的核心上下文。view命令则用于查看完整的对话原文。# 查看完整对话 ch view a1b2c3d4 # 以纯文本格式查看便于用 grep, head 等工具进行二次处理 ch view a1b2c3d4 --plain | grep -A 5 -B 5 “docker run” # 查看并包含工具调用的具体名称如 bash_command, read_file ch view a1b2c3d4 --tools3.2.4 导出与复用 (export与resume)export能将对话导出为结构清晰的 Markdown 文件方便分享、归档或放入笔记软件。ch export a1b2c3d4 -o ~/notes/claude_sessions/docker_fix.mdresume是 Claude Code 用户的专属利器。它可以直接在 Claude Code 中重新打开一个历史会话让你在完全相同的上下文中继续对话。这个功能对于中断后继续工作、或者基于历史会话提出新问题来说体验是无缝的。ch resume a1b2c3d4 # 执行后你的 Claude Code 界面会跳转到这个历史会话。3.3 为 AI Agent 安装技能Skill这是将chat-history从个人工具升级为团队协作或智能工作流的关键一步。安装技能后Claude Code 或 Cursor 中的 AI Agent 在与你对话时能够主动调用这个工具去搜索你的历史会话从而获得更连续的上下文。chat-history install-skill这个命令会在~/.cursor/skills/和~/.claude/skills/目录下分别创建一个chat-history文件夹并将内置的SKILL.md描述文件放入其中。AI Agent 在启动时会读取这些技能描述从而知道如何调用chat-history命令来搜索历史。实操心得安装技能后你可以尝试对 Agent 说“看看我之前有没有遇到过类似的WebSocket连接超时的问题” 有技能的 Agent 可能会在后台执行类似ch search “WebSocket timeout” --deep --timeframe month的命令并将找到的相关历史会话摘要作为上下文提供给当前的对话。这相当于让你的 AI 助手拥有了“长期记忆”。重要提示每次通过cargo install升级chat-history后都应该重新运行一次install-skill命令以确保 Agent 使用的技能描述文件是最新版本包含所有最新的参数和能力说明。4. 高级技巧与排查指南4.1 搜索策略优化如何精准找到你想要的内容单纯输入关键词可能返回太多结果。掌握以下策略能让你成为搜索高手善用--scope参数这是很多人忽略的利器。它内置了多种针对开发者场景的优化搜索模式。--scope errors当你只记得错误信息片段时使用。它会提升错误信息、堆栈跟踪at ...、日志级别ERROR等内容的相关性权重。--scope files当你想找涉及特定文件操作的对话时使用。它会优先匹配文件路径/src/components/、read_file/write_file工具调用等。--scope tools用于查找使用了特定工具如bash_command,search_files的对话。--scope similar当你有一个较长的查询如一段错误信息想找语义上相似的过去查询时使用。它基于词向量进行简单相似度计算。组合过滤条件时间--from/--to、分支--branch、项目源--source claude等过滤器可以任意组合。最有效的组合通常是时间 分支 关键词。理解评分★搜索结果前的星级如★7.2是相关度评分。通常高于★5.0的结果来自索引搜索是高度相关的低于★5.0的结果可能来自深度搜索或者是匹配度稍弱的索引结果。评分可以帮助你快速判断结果质量。4.2 数据源与文件结构解析理解工具从哪里读取数据有助于排查“为什么找不到某个会话”的问题。来源默认路径工具读取的内容注意事项Claude Code~/.claude/projects/*/1.sessions-index.json(索引)2.*.jsonl(完整会话)确保 Claude Code 的“保存会话历史”功能已开启。每个项目文件夹对应一个 IDE 窗口或工作区。Cursor~/.cursor/projects/*/agent-transcripts/*.jsonl或*.txt文件Cursor 的转录文件可能因版本或设置而异。chat-history能自动识别两种格式。常见问题1工具报告“No sessions found”检查路径首先确认工具是否在读取正确的目录。你可以通过ch -v查看它扫描的会话路径。检查数据手动去~/.claude/projects/或~/.cursor/projects/下看看是否有对应的项目文件夹和会话文件。如果文件夹为空可能是 Claude Code/Cursor 没有保存历史记录需要在它们的设置中启用。权限问题确保当前用户有读取这些目录和文件的权限。常见问题2搜索不到已知存在的会话内容确认搜索模式如果你搜索的是对话中间某句很具体的话请务必加上--deep参数。索引搜索只覆盖摘要、首条提示和分支。检查过滤条件是否无意中设置了--from、--to或--branch过滤器把目标会话排除在外了内容被过滤工具会自动过滤掉“热身”消息如“I‘m Claude”、/clear指令等噪音。极少数情况下如果你的目标内容恰好和这些噪音模式重合可能会被过滤。但这在正常开发对话中很少见。常见问题3安装技能后Agent 仍不调用历史搜索确认安装路径技能文件必须准确安装在~/.cursor/skills/chat-history/SKILL.md和~/.claude/skills/chat-history/SKILL.md。运行install-skill命令通常能正确完成。重启 Agent/IDE安装新技能后可能需要重启 Claude Code 或 Cursor 的 AI Agent 界面它才会重新加载技能列表。Agent 的自主性即使拥有技能Agent 也不会在每次对话中都主动搜索历史。它通常只在判断历史信息可能对当前问题有帮助时才会调用。你可以通过更明确的指令引导它例如“请搜索我的历史对话看看我之前是如何配置Nginx反向代理的。”4.3 性能调优与处理大量历史数据当你积累了成千上万个会话后首次运行或深度搜索可能会变慢。以下是一些建议利用索引搜索日常搜索尽量依赖默认的索引搜索。确保你的sessions-index.json文件能正常生成这是 Claude Code 的责任。索引搜索的性能几乎不受会话总数影响。限制搜索范围养成使用--timeframe如--timeframe month或--from/--to的习惯避免无必要地扫描全部历史。并行度调整高级深度搜索默认使用rayon的全局并行池。如果你的机器 CPU 核心数非常多且 IO 不是瓶颈例如使用 NVMe SSD理论上你可以通过修改环境变量RAYON_NUM_THREADS来调整并行线程数但通常默认设置已是最优。这个工具从根本上改变了我与AI编程助手的协作方式。它把一次性的、孤立的对话变成了一个可检索、可延续的知识库。最大的体会是主动管理对话上下文与被动记录同样重要。我现在会习惯性地在对话结束时让 Claude 生成一个更准确的会话摘要例如“优化了X功能的数据库查询使用了Y索引性能提升Z%”这能极大提升未来索引搜索的命中率。chat-history提供的不仅是一个搜索框更是一种让AI助手的工作成果得以沉淀和复用的方法论。