Session-Buddy

技能简介

Session-Buddy 是一款面向 Claude Code 的会话生命周期管理与记忆 MCP 服务器，由 Python 驱动的 FastMCP 框架构建，通过本地 DuckDB 数据库实现会话记忆的持久化存储与语义检索。它能够自动感知 Git 仓库，在 Claude Code 连接时自动初始化会话、在断开时自动清理，并通过检查点（checkpoint）机制捕获开发者的反思与学习内容，供后续会话复用。Session-Buddy 既是独立的 MCP 服务器，也可融入 Bodai 生态，与 Crackerjack（质量门禁）、Mahavishnu（编排层）等组件协同工作。

核心能力

• 自动会话生命周期管理：Git 仓库下连接即自动启动会话（AutoStart），断开时自动执行清理与交接（AutoEnd），无需手动干预。
• DuckDB 本地记忆存储：所有会话反思、对话上下文以结构化数据存入本地 DuckDB，无需云端 embedding 服务，文本搜索开箱即用；语义搜索可按需配置 Ollama 或 llama-server 等 HTTP embedding 提供者。
• 跨项目智能检索：支持按文本、概念、文件路径、项目、时间范围等多种维度检索记忆；可建立项目组与依赖关系，让跨仓库检索结果携带项目上下文权重。
• Crackerjack 质量门禁集成：自动记录代码检查、类型检查、安全扫描、测试运行的结果与失败模式，作为会话上下文供后续检查点复用。
• 签名能力元数据发布：通过 MCP 工具对外暴露 session_buddy_list_skills、session_buddy_get_skill、session_buddy_list_agents、session_buddy_get_agent，使 MCP 客户端能动态感知服务器当前技能目录。
• 可观测性指标：内置 Prometheus 指标、WebSocket 监控、运行健康检查，支持与外部监控系统集成。
• 确定性洞察捕获：通过内容哈希去重机制，在检查点与会话结束时自动提取反思内容，确保每次捕获的知识不重复。

安装与配置

前置要求

• Python 3.14+
• uv 包管理器（或 pip）
• 支持 Streamable HTTP 的 MCP 客户端

安装步骤

# 方式一：从源码克隆
git clone https://github.com/lesleslie/session-buddy.git
cd session-buddy
uv sync

# 启动 MCP 服务（默认监听 127.0.0.1:8678）
uv run session-buddy server start

# 方式二：通过 uvx 直接运行
uvx session-buddy server start

MCP 客户端配置

在 Claude Code 或其他 MCP 客户端的配置文件（~/.claude/settings.json 或 MCP 客户端对应配置）中添加：

{
  "mcpServers": {
    "session-buddy": {
      "type": "http",
      "url": "http://127.0.0.1:8678/mcp"
    }
  }
}

配置文件层级

Session-Buddy 采用 Oneiric 分层配置模型，支持多层覆盖：

• settings/session-buddy.yaml — 提交到仓库的默认配置
• settings/local.yaml — 本地覆盖（被 gitignore）
• settings/lite.yaml / settings/standard.yaml — 模式特定配置
• ~/.config/session-buddy/config.yaml — 用户级配置
• 环境变量（SESSION_BUDDY_ 前缀）

使用步骤

第一步：连接 MCP 客户端

启动服务后，在 Claude Code 中加载 session-buddy MCP 服务。Git 仓库下首次连接会自动检测并初始化会话。

第二步：发起会话（自动或手动）

Git 仓库下连接即自动启动；非 Git 项目可手动执行：

/session-buddy:start

第三步：日常开发与检查点

开发过程中随时保存检查点，捕获当前进展与反思：

/session-buddy:checkpoint
/session-buddy:store_reflection

检查点会记录：当前文件、进度备注、失败模式与解决方案，以及质量信号（来自 Crackerjack）。

第四步：跨会话记忆检索

在新的会话或不同项目中检索已有记忆：

/session-buddy:quick_search   # 快速全文搜索
/session-buddy:search_by_file # 按文件路径搜索相关记忆
/session-buddy:search_summary # 按概念检索

第五步：结束会话

断开连接时自动触发清理；也可手动结束：

/session-buddy:end

适用场景

• 大型多仓库项目：在 monorepo 或微服务多仓库场景中，Session-Buddy 能记住每个仓库的历史技术决策与问题模式，新会话无需重新摸索。
• 长期迭代的功能开发：需要跨越数天甚至数周的功能，通过检查点机制保持上下文连续性，避免 Claude Code 长会话衰减问题。
• Code Review 与质量门禁：配合 Crackerjack 集成，每次提交的质量报告自动沉淀为可检索知识，下次 Review 时 Claude Code 可直接引用历史失败模式。
• 团队知识传承：开发者在会话中记录的反思与解决方案，可被团队其他成员通过跨项目检索发现和复用，形成项目级知识图谱。
• 调试与问题追溯：当某个 Bug 在不同时间出现时，通过时间范围检索快速定位历史上是否有过类似记录及对应的解决方案。

适用人群

• Claude Code 重度用户：经常在大型或长期项目中工作的开发者，会话记忆需求强烈。
• 多仓库维护者：同时管理多个 Git 仓库，需要跨项目保持上下文一致性的工程师。
• 重视代码质量的团队：已将 Crackerjack 等质量工具集成到开发流程的团队，Session-Buddy 是其质量信号的最佳沉淀层。
• AI 编程研究者：对 AI 编程工具的会话管理与记忆机制感兴趣的技术人员，Session-Buddy 源码结构清晰，适合作为学习参考。

工作原理

Session-Buddy 的核心架构分为三层：

MCP 协议层：基于 FastMCP 框架实现标准 Model Context Protocol 接口，以 Streamable HTTP 方式暴露工具。客户端连接后，通过 SESSION_BUDDY_TOOL_PROFILE 选择工具暴露范围（minimal / standard / full）。

会话管理层：Oneiric 运行时提供统一的生命周期与配置抽象。Git 仓库场景下，通过 Git hooks 风格的自动检测触发 start/end；非 Git 场景通过显式 MCP 工具调用管理。

存储层：DuckDB 作为本地 OLAP 引擎，存储会话检查点、反思记录、质量信号。文本搜索基于 DuckDB 内置 FTS（全文搜索），语义搜索通过可插拔的 HTTP embedding 提供者（如 Ollama）实现降级策略：配置了提供者时走语义检索，未配置时回退到全文搜索，保证基本功能可用。

官方链接

• PyPI 主页：https://pypi.org/project/session-buddy/
• GitHub 仓库：https://github.com/lesleslie/session-buddy
• Bodai 生态说明：https://github.com/lesleslie/bodai
• Crackerjack 质量工具：https://github.com/lesleslie/crackerjack