内容
# 克劳德历史
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://github.com/sydasif/claude-history-mcp)
**为 `Claude` 构建的内存搜索 `MCP`** - 搜索每一次对话、每个会话、每个项目。您的完整开发历史记录，可以在几秒钟内查询。
> **工作原理：** Claude Code 将对话数据存储在 `~/.claude/projects/**/*.jsonl` 中。Claude 历史记录 MCP 解析这些文件，将它们缓存在 SQLite 中，并提供工具让 Claude 可以按需搜索您的完整开发历史记录。
---
## 功能
| 功能 | 描述 |
| --- | --- |
| **全文搜索** | 跨所有会话消息、工具输出和历史记录命令进行搜索 |
| **自然语言日期** | 按“昨天”、“上周”、“2026年3月”过滤 - 由 `dateparser` 提供支持 |
| **增量解析** | 仅重新解析更改的文件（基于 mtime 的 SQLite 缓存） |
| **10 个 MCP 工具** | 搜索、列出、过滤、分析 - 所有列表/搜索工具均支持分页 |
| **成本分析** | 估计代币成本、使用趋势、模型细分和工具频率 |
| **会话层次结构** | 树视图：项目 → 会话 → 消息，支持通配符模式搜索 |
| **零配置** | 指向现有的 `~/.claude/` 数据 - 无需设置，无需 API 密钥，无需云 |
| **安全代理** | 处理现实世界的 JSONL 边缘情况（缺少时间戳、截断的工具名称、代理字符） |
---
## 快速入门
**先决条件：** 已安装 Python 3.12+ 和 [uv](https://docs.astral.sh/uv/getting-started/installation/)。
```bash
# 添加到 Claude Code（用户范围 - 在所有项目中可用）
claude mcp add claude-history --scope user -- uvx --from git+https://github.com/sydasif/claude-history-mcp claude-history-mcp
```
**就这样。** 下次您打开 Claude Code 时，您将拥有一个可搜索的内存。
---
## 您可以使用
| 问题 | 工具 | 示例 |
| --- | --- | --- |
| “我上周在做什么？” | `list_recent_activity` | `list_recent_activity(hours=168)` |
| “查找有关支付处理的会话” | `search_messages` | `search_messages(query="payment", role="user")` |
| “显示我调试超时时的会话” | `list_session_transcript` | `list_session_transcript(session_id="abc123...")` |
| “重构的代币成本是多少？” | `list_session_stats` | `list_session_stats(session_id="abc123...")` |
| “我运行了哪些命令来部署？” | `search_history` | `search_history(query="terraform apply")` |
| “列出所有项目及其活动” | `list_sessions_stats` | `list_sessions_stats()` |
| “上个月来自 auth 项目的会话” | `list_sessions_stats` | `list_sessions_stats(project="auth", from_date="last month")` |
| “我正在使用哪些模型，成本是多少？” | `list_model_usage` | `list_model_usage()` |
| “我最常使用哪些工具？” | `list_tool_usage` | `list_tool_usage()` |
| “显示项目层次结构树” | `list_project_tree` | `list_project_tree(project="auth")` |
| “获取项目的聚合统计信息” | `list_project_stats` | `list_project_stats(project="auth")` |
所有列表/搜索工具都支持基于游标的分页的 `offset`。
---
## 架构
```text
~/.claude/projects/**/*.jsonl ──┐
~/.claude/history.jsonl ──┤
▼
┌──────────────────────────────────────────────────────┐
│ claude-history-mcp (MCP Server) │
│ ┌─────────────┐ ┌────────────┐ ┌───────────────┐ │
│ │ 工具 │ │ 资源 │ │ 搜索引擎 │ │
│ │ （搜索、 │ │ （项目、 │ │ （全文、 │ │
│ │ 列出、 │ │ 历史记录）│ │ 过滤器、 │ │
│ │ 获取、统计）│ │ │ │ 聚合） │ │
│ └──────┬──────┘ └─────┬──────┘ └───────┬───────┘ │
│ │ │ │ │
│ ┌──────┴───────────────┴──────────────────┴───────┐ │
│ │ SQLite 缓存层 │ │
│ │ 项目 │ 会话 │ 消息 │ 历史记录 │ │
│ └─────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────┘
```
---
## 开发
```bash
# 安装开发依赖项
uv sync --group dev
# 运行测试（隔离的 HOME - 永远不会触及真实的 ~/.claude）
uv run pytest -v
# 运行覆盖率测试
uv run pytest --cov=claude_history_mcp
# 清除并重建缓存
python -c "from claude_history_mcp import initialize; initialize(force=True)"
```
---
## 贡献
1. 分叉仓库
2. 创建分支：`git checkout -b feature/your-feature`
3. 安装开发依赖项：`uv sync --group dev`
4. 运行测试：`uv run pytest -v`
5. 提交包含更改描述的 PR
---
## 许可证
MIT
