Claude-labbook

克劳德实验书

 ](https://nodejs.org/)

AI编码代理的持续实验跟踪和语义代码搜索——永远不要重复失败的方法。

LabBook是一个 MCP服务器 这为Claude Code（和其他兼容MCP的代理）提供了一个持久的记忆，可以记住尝试了什么、成功了什么、失败了什么以及为什么。当上下文窗口压缩或新对话开始时，LabBook会恢复完整的历史记录，以便代理可以从中断的地方继续。

______________________________________________________________________

问题

AI编码代理失去上下文。经过长时间的会话后，上下文窗口会压缩，代理会忘记它已经尝试过的内容。它重新尝试相同的失败修复，恢复工作代码，或重新发现相同的死胡同——浪费时间和令牌。

LabBook如何解决这个问题

LabBook将实验历史保存在本地图形数据库（Kuzu）和矢量存储（LanceDB）中。每次代码更改都会记录为 试验 其结果。在修改代码之前，代理会检查已经尝试过的操作。在上下文压缩后，单个 get_briefing 通话可恢复完整画面。

______________________________________________________________________

特性

• 会话跟踪 --将小组相关试验转化为问题解决环节
• 试验记录 --记录每次代码更改的结果（成功/失败/部分/恢复）和关键经验教训
• 决策记录 --用基本原理捕捉架构决策，取代过时的决策
• 环境事实 --在对话中持久化特定于机器的详细信息（命令、路径、端口）
• 变更前检查 --在修改代码之前，对该组件进行预先试验和主动决策
• 语义代码搜索 --对代码库进行索引，并按代码搜索 *做*，而不仅仅是关键字
• 增量索引 --仅重新索引内容已更改的文件（SHA-256内容哈希）
• 自动生成简报 — .claude/experiment_log.md 每次写入后都会重新生成，提供人类可读的日志
• 基于图形的关系 --试验链接到组件，组件映射到代码文件，决策应用于组件，试验链到之前的试验

快速开始

先决条件

安装

npm install -g claude-labbook

或者直接运行：

npx claude-labbook

或者克隆并从源代码构建：

git clone https://github.com/anthonylee991/claude-labbook.git
cd claude-labbook
npm install
npm run build

MCP集成

LabBook是一个MCP服务器，旨在供AI代理使用，而不是独立运行。看 MCP设置指南 了解每个编辑器的分步说明。

克劳德代码（CLI/VS代码）：

claude mcp add labbook -s user -- npx claude-labbook

克劳德桌面/光标/风帆 --添加到MCP配置文件(位置):

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

看 MCP设置指南 有关Claude Code、Claude Desktop、Cursor、Windsurf和其他MCP兼容编辑器的详细说明。

代理说明（重要）

当代理人被告知时，LabBook的效果最好 *当* 调用每个工具。在系统提示中添加说明或 CLAUDE.md 文件--请参见 代理说明 作为一个现成的示例。

工具

LabBook公开了12个MCP工具：

运作原理

存储

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)

文档

贡献

欢迎捐款，但该项目将尽最大努力进行维护。PR可能不会立即审查。看 贡献.md 作为指导方针。

许可证

Apache 2.0——请参阅 许可证 了解详情。