Claude Historian

🚀 claude-historian

claude-historian 是一個用於搜索 Claude Code 對話歷史的模型上下文協議（MCP）服務器。藉助它，你可以查找過往解決方案、追蹤文件變更，並從之前的工作中汲取經驗。

🚀 快速開始

安裝要求

• Claude Code

安裝方式

從 shell 安裝

claude mcp add claude-historian -- npx claude-historian

從 Claude 內部安裝（需要重啟）

Add this to our global mcp config: npx claude-historian

Install this mcp: https://github.com/Vvkmnn/claude-historian

從手動配置的 mcp.json 安裝（Cursor、Windsurf 等）

{
  "mcpServers": {
    "claude-historian": {
      "command": "npx",
      "args": ["claude-historian"],
      "env": {}
    }
  }
}

安裝完成。無需執行 npm install，因為它沒有外部依賴或本地數據庫，僅包含搜索算法。

✨ 主要特性

這是一個 MCP 服務器，可讓 Claude 訪問你的對話歷史。它具備智能優先級排序功能，搜索速度快。

它可以在本地運行（帶著酷炫的標誌 [⌐■_■]）：

[⌐■_■] search_conversations query=<query>
  > "How did we fix that Redis connection pooling nightmare?"
  > "Docker container keeps crashing on Kubernetes deployment"
  > "React infinite re-render loop - useEffect dependency hell"

[⌐□_□] find_file_context filepath=<filepath>
  > "package.json changes that broke everything last month"
  > "When we accidentally committed .env to main branch"
  > "Authentication service refactor - before/after comparison"

[⌐×_×] get_error_solutions error_pattern=<error>
  > "MODULE_NOT_FOUND - the classic npm/yarn version mismatch"
  > "CORS preflight failing - but only on production Fridays?"
  > "Database deadlock during Black Friday traffic spike"

[⌐◆_◆] find_similar_queries query=<query>
  > "Database queries slower than my morning coffee brewing"
  > "How to implement error boundaries without losing sanity"
  > "State management: Redux vs Zustand vs just useState"

[⌐○_○] list_recent_sessions
  > "Tuesday debugging marathon: 9pm-3am flaky test hunt"
  > "Performance optimization sprint - reduced bundle 40%"
  > "The great TypeScript migration of 2024"

[⌐⎚_⎚] find_tool_patterns tool_name=<tool>
  > "Read → Edit → Bash combo for rapid prototyping"
  > "When I use Grep vs Task for different searches"
  > "Git operations during feature branch management"

🔧 技術細節

工作原理

claude-historian 的工作方式如下（源代碼）：

"docker auth" query
      |
      ├─> Classify: implementation query -> boost tool examples
      |
      ├─> Stream & Filter:
      |   • Summary messages -> priority queue *****
      |   • Tool usage context -> high value ****
      |   • Error solutions -> targeted ***
      |
      ├─> Smart Ranking:
      |   • "Fixed Docker auth with Read tool" (2h ago) *****
      |   • "OAuth implementation approach" (yesterday) ****
      |   • "Container auth debug" (last week) ***
      |
      └─> Return Claude Code optimized results

採用的技術

• JSON 流式解析器：按需讀取 Claude Code 對話文件，無需完全反序列化。
• LRU 緩存：內存緩存，具備智能淘汰機制，用於頻繁訪問的對話。
• 受 TF-IDF 啟發的評分：使用詞頻評分和文檔頻率加權來確定相關性。
• 查詢分類：採用樸素貝葉斯風格的分類（錯誤/實現/分析/通用），並具有自適應限制。
• 編輯距離：對技術術語進行模糊匹配，並能容忍拼寫錯誤。
• 指數時間衰減：近期消息權重更高，半衰期可配置。

文件訪問

• 從 ~/.claude/conversations/ 讀取文件。
• 無需持久存儲或索引。
• 數據不會離開你的設備。

📦 開發指南

克隆倉庫並安裝依賴

git clone https://github.com/vvkmnn/claude-historian && cd claude-historian
npm install && npm run build
npm test

貢獻代碼

• 請 Fork 倉庫並創建功能分支。
• 在提交 PR 之前，使用大量對話歷史進行測試。
• 遵循 TypeScript 嚴格模式和 MCP 協議 標準。

參考示例

• 官方 MCP 服務器 可作為參考實現。
• TypeScript SDK 可提供最佳實踐。

📄 許可證

本項目採用 MIT 許可證。

Claude Fauchet (1744 - 1793)，法國曆史學家