AI导哈

实验跟踪与语义代码搜索工具

LabBook是一个为AI编程代理提供持久化实验跟踪和语义代码搜索的MCP服务器，帮助代理避免重复尝试失败的方法。

  • by anthonylee991
  • TypeScript
  • 本地部署
  • 15 星标
  • 更新于
在 GitHub 查看 anthonylee991/claude-labbook

使用说明

克劳德实验书

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工具：

工具 说明
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——请参阅 许可证 了解详情。

相关 MCP