克劳德实验书
AI编码代理的持续实验跟踪和语义代码搜索——永远不要重复失败的方法。
LabBook是一个 MCP服务器 这为Claude Code(和其他兼容MCP的代理)提供了一个持久的记忆,可以记住尝试了什么、成功了什么、失败了什么以及为什么。当上下文窗口压缩或新对话开始时,LabBook会恢复完整的历史记录,以便代理可以从中断的地方继续。
问题
AI编码代理失去上下文。经过长时间的会话后,上下文窗口会压缩,代理会忘记它已经尝试过的内容。它重新尝试相同的失败修复,恢复工作代码,或重新发现相同的死胡同——浪费时间和令牌。
LabBook如何解决这个问题
LabBook将实验历史保存在本地图形数据库(Kuzu)和矢量存储(LanceDB)中。每次代码更改都会记录为 试验 其结果。在修改代码之前,代理会检查已经尝试过的操作。在上下文压缩后,单个 get_briefing 通话可恢复完整画面。
特性
- 会话跟踪 --将小组相关试验转化为问题解决环节
- 试验记录 --记录每次代码更改的结果(成功/失败/部分/恢复)和关键经验教训
- 决策记录 --用基本原理捕捉架构决策,取代过时的决策
- 环境事实 --在对话中持久化特定于机器的详细信息(命令、路径、端口)
- 变更前检查 --在修改代码之前,对该组件进行预先试验和主动决策
- 语义代码搜索 --对代码库进行索引,并按代码搜索 做,而不仅仅是关键字
- 增量索引 --仅重新索引内容已更改的文件(SHA-256内容哈希)
- 自动生成简报 —
.claude/experiment_log.md每次写入后都会重新生成,提供人类可读的日志 - 基于图形的关系 --试验链接到组件,组件映射到代码文件,决策应用于组件,试验链到之前的试验
快速开始
先决条件
- Node.js 20+
安装```bash
npm install -g claude-labbook
或者直接运行:```bash
npx claude-labbook
或者克隆并从源代码构建:```bash
git clone https://github.com/anthonylee991/claude-labbook.git
cd claude-labbook
npm install
npm run build
### MCP集成
LabBook是一个MCP服务器,旨在供AI代理使用,而不是独立运行。看 MCP设置指南 了解每个编辑器的分步说明。
**克劳德代码(CLI/VS代码):**```bash
claude mcp add labbook -s user -- npx claude-labbook
克劳德桌面/光标/风帆 --添加到MCP配置文件(位置):```json
{
"mcpServers": {
"labbook": {
"command": "npx",
"args": ["claude-labbook"]
}
}
}
看 MCP设置指南 有关Claude Code、Claude Desktop、Cursor、Windsurf和其他MCP兼容编辑器的详细说明。
### 代理说明(重要)
当代理人被告知时,LabBook的效果最好 *当* 调用每个工具。在系统提示中添加说明或 `CLAUDE.md` 文件--请参见 代理说明 作为一个现成的示例。
## 工具
LabBook公开了12个MCP工具:
|工具|说明|
|------|-------------|
| `start_session` |针对问题或功能启动新的实验会话|
| `resolve_session` |将会话标记为已解决、已放弃或已暂停|
| `list_sessions` |列出按状态筛选的会话|
| `log_trial` |记录代码更改的结果(核心工具)|
| `get_trial_chain` |跟随试验链,看看尝试的演变|
| `log_decision` |记录架构或战略决策|
| `log_env_fact` |记录特定于机器或环境的详细信息|
| `get_env_facts` |检索环境事实|
| `get_briefing` |获取所有活动会话、试验和决策的简明摘要|
| `check_before_change` |在修改组件之前,检查之前的试验和决定|
| `scan_codebase` |索引或重新索引项目代码库以进行语义搜索|
| `search_code` |跨索引代码库的语义搜索|
## 运作原理
### 存储
LabBook将数据存储在 `.claude/labbook/` 在您的项目目录中:
- **立体主义** (图形数据库)--会话、试验、组件、决策、环境事实、代码文件以及它们之间的所有关系
- **LanceDB** (向量存储)——试验和代码块语义搜索的嵌入
- **禁食** (`all-MiniLM-L6-v2`)-本地嵌入模型,不需要API调用
### 图形架构```
Session ──CONTAINS──> Trial ──MODIFIES──> Component ──MAPS_TO──> CodeFile
│ │ ▲
│ └──LED_TO──> Trial │
│ │
└── Decision ──APPLIES_TO─────────────────┘
│
└──SUPERSEDES──> Decision
自动生成简报
每次写入操作后,LabBook都会重新生成 .claude/experiment_log.md --总结活动会话、试验的Markdown文件(带有结果图标✅❌⚠️↩️), 决策和环境事实。此文件是人类可读的,可以提交给版本控制。
建筑```
src/
├── db/ # Database layer
│ ├── kuzu.ts # Graph database (sessions, trials, components, decisions)
│ ├── lance.ts # Vector store (trial + code embeddings)
│ └── ids.ts # Auto-increment ID manager
├── scanner/ # Codebase indexing
│ ├── walker.ts # Directory traversal (.gitignore-aware)
│ ├── chunker.ts # Source code chunking (logical boundary splitting)
│ └── languages.ts # File extension → language mapping
├── tools/ # MCP tool implementations
│ ├── sessions.ts # start_session, resolve_session, list_sessions
│ ├── trials.ts # log_trial, get_trial_chain
│ ├── decisions.ts # log_decision
│ ├── env-facts.ts # log_env_fact, get_env_facts
│ ├── briefing.ts # get_briefing
│ ├── check.ts # check_before_change
│ ├── scan.ts # scan_codebase
│ └── search.ts # search_code
├── embeddings.ts # fastembed wrapper (all-MiniLM-L6-v2, 384 dims)
├── formatting.ts # Shared formatting for trials, sessions, decisions
├── summary.ts # Auto-generates .claude/experiment_log.md
├── server.ts # MCP server setup and tool dispatch
└── index.ts # Entry point (stdio transport)
```
文档
| 文档 | 描述 |
|---|---|
| MCP设置指南 | 为所有支持的编辑器逐步配置MCP |
贡献
欢迎捐款,但该项目将尽最大努力进行维护。PR可能不会立即审查。看 贡献.md 作为指导方针。
许可证
Apache 2.0——请参阅 许可证 了解详情。
