BHGBrain：为你的 AI 智能体提供一个共享的持久记忆

你使用的每一个 AI 编码智能体——Claude Code、Codex、Copilot、Gemini——每次会话都从失忆开始。昨天的调试突破、上周的架构决策、三个冲刺前团队达成的编码标准——全部消失。你要么重新解释一切，要么指望智能体从恰好打开的文件中推断出来。

这是当今智能体工作流中最大的摩擦点。不是模型质量。不是工具集成。而是记忆。

BHGBrain 是我们的答案：一个开源的 MCP 服务器，为你的 AI 智能体提供一个持久的、可搜索的、共享的第二大脑。

问题：每个智能体都是一条金鱼

如果你在真实项目中使用过 AI 编码智能体，你一定熟悉这个模式：

1. **上午会话：**你解释你的架构、约束和约定。智能体干得不错。
2. **下午会话：**新的上下文窗口。智能体提出了你四小时前告诉它要避免的精确模式。
3. **第二天：**另一个不同的智能体（也许是用于后台任务的 Codex）对 Claude Code 昨天学到的东西一无所知。

这些应对方法都很脆弱：

• MEMORY.md 文件在达到 500 行之前还能用，之后每条消息都会消耗你 15% 的上下文窗口。
• 系统提示是静态的，无法捕捉不断演进的知识。
• 会话记录是特定于智能体的，且不可搜索。
• 手动重新解释正是我们当初使用智能体想要避免的事情。

根本问题在于：每个智能体都有自己短暂的上下文，且它们彼此之间互不通信。

BHGBrain 做了什么

BHGBrain 是一个 MCP 服务器——这意味着任何兼容 MCP 的 AI 客户端都可以将其作为工具连接。它暴露了一组简单的操作：

在底层，每条记忆都会获得：

• 向量嵌入存储在 Qdrant 中，用于语义搜索
• 元数据和全文索引存储在 SQLite 中，用于快速过滤和关键词搜索
• 自动去重——如果你告诉它同样的内容两次，它会合并而不是复制
• 类型分类——记忆被分类为情景式（事件）、语义式（事实）或程序式（工作流）

写入流水线

当智能体调用 remember 时，BHGBrain 不会只是把文本倒进数据库。它运行一个多阶段流水线：

1. 抽取——一个 LLM 将原始输入拆分为原子记忆候选，并推断类型、标签和重要性分数。
2. 决策——每个候选与同一命名空间中的现有记忆进行比较。系统决定：ADD（新知识）、UPDATE（细化已有）、DELETE（使旧信息失效）或 NOOP（已知内容）。
3. 存储——被接受的记忆会被嵌入、索引并持久化。

如果抽取模型不可用，BHGBrain 会回退到使用内容哈希和余弦相似度阈值的确定性去重。它绝不会静默丢弃一条记忆。

读取路径

当智能体需要上下文时，它调用 recall 或 search：

• 语义搜索按含义查找记忆（“这个项目里的认证是怎么工作的？"）
• 全文搜索查找精确术语（“OIDC federated credentials”）
• 混合搜索使用 Reciprocal Rank Fusion 结合两者（默认 70% 语义，30% 全文）

还有一个 memory://inject——一个特殊的 MCP 资源，在会话开始时交付一个有预算的上下文块，让智能体在无需手动提示的情况下以相关知识开始。

为什么一个共享大脑能改变一切

真正的力量不在于一个智能体能记住东西。而在于你所有的智能体共享同一份记忆。

场景：多智能体开发

你在一个项目上运行三个智能体：

• Claude Code 用于 IDE 中的交互式开发
• Codex 用于后台任务（测试生成、重构）
• OpenClaw 用于运维和部署自动化

没有共享记忆，每个智能体都在孤立中运作。Claude Code 学会了你的命名约定；Codex 生成的测试却违反了这些约定。OpenClaw 部署的配置与 Claude Code 昨天记录的架构决策相矛盾。

有了 BHGBrain，当 Claude Code 存储 "All API routes use kebab-case and return RFC 7807 problem details" 时，Codex 在下一次 recall 中就能获取到并生成合规的测试。OpenClaw 的部署脚本与同样的约定对齐。一条记忆，三个智能体，零漂移。

场景：入职与知识传承

新团队成员加入。他们无需阅读 40 页 wiki 文档（一半已过时），而是将他们的 AI 智能体连接到团队的 BHGBrain 实例。该智能体立即可以访问：

• 架构决策及其理由
• 带具体示例的编码标准
• 已知的陷阱和应对方法
• 项目专属术语

BHGBrain 附带的引导提示词会引导完成一个结构化的 10 节访谈，涵盖身份、职责、目标、工具、实体地图和运行规则——在大约 30 分钟内构建出一份全面的工作档案。

场景：跨仓库连续性

在多个仓库间工作（在微服务、单体仓库拆分或多组织咨询中很常见）？BHGBrain 的命名空间和集合系统让知识井然有序：

• 命名空间 project-alpha 存放该项目专属的记忆
• 命名空间 global 存放跨领域的标准
• 命名空间内的集合将相关记忆分组（例如 api-design、infrastructure、security）

智能体自动查询正确的作用域。没有交叉污染，没有丢失的上下文。

架构：简单且自托管

BHGBrain 在你的机器或你的基础设施上运行。除了嵌入 API 之外没有云依赖（而且即使这一点在使用本地模型时也是可选的）。

MCP Clients (Claude / Codex / OpenClaw / etc.)
  → MCP transport (HTTP or stdio)
  → BHGBrain server
      → Write pipeline (extraction + dedup + decision)
      → Qdrant (vector search)
      → SQLite (metadata, fulltext, categories, audit log)

要求：

• Node.js 20+
• Qdrant（Docker 一行命令：docker run -d --name qdrant -p 6333:6333 qdrant/qdrant）
• OpenAI API 密钥（用于嵌入）——或者使用 Ollama 配合 nomic-embed-text 实现完全本地运行

安装并运行：

git clone https://github.com/Big-Hat-Group-Inc/BHGBrain.git
cd BHGBrain
npm install && npm run build
export OPENAI_API_KEY=sk-...
export BHGBRAIN_TOKEN=$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")
node dist/index.js

就这样。你的智能体现在可以通过 stdio（本地）或 HTTP（联网）连接。

默认即企业就绪

BHGBrain 不是玩具。它从第一天起就考虑了生产环境的关注点：

• **认证：**非环回 HTTP 连接需要 bearer token。失败即关闭——如果未设置 token 环境变量且你绑定到非环回地址，服务器会拒绝启动。
• **速率限制：**默认每客户端每分钟 100 个请求。
• **审计日志：**每次写入和删除都会记录时间戳、命名空间、客户端 ID 和操作类型。
• **密钥扫描：**记忆在存储前会检查凭证模式。疑似密钥会被拒绝。
• **备份与恢复：**完整的 SQLite + Qdrant 快照，带完整性校验。
• **优雅降级：**如果 Qdrant 宕机，读取回退到 SQLite 全文。如果嵌入 API 不可用，服务器进入降级模式而不是崩溃。
• **结构化日志：**JSON 日志，自动对 token 和内容进行脱敏。

5 分钟入门

1. 启动 Qdrant

docker run -d --name qdrant -p 6333:6333 qdrant/qdrant

2. 安装 BHGBrain

git clone https://github.com/Big-Hat-Group-Inc/BHGBrain.git
cd BHGBrain && npm install && npm run build

3. 配置你的智能体

对于 Claude Desktop，添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "bhgbrain": {
      "command": "node",
      "args": ["/path/to/BHGBrain/dist/index.js"],
      "env": { "OPENAI_API_KEY": "sk-..." }
    }
  }
}

对于 HTTP 客户端（OpenClaw、mcporter、远程智能体）：

{
  "mcpServers": {
    "bhgbrain": {
      "transport": "http",
      "url": "http://127.0.0.1:3721",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

4. 开始记忆

让你的智能体记住一些东西：

“Remember: our API uses kebab-case routes, returns RFC 7807 problem details, and all endpoints require Bearer token authentication.”

BHGBrain 会存储它，将其分类为 semantic，适当地打标签，并通过 recall 使其可供每个已连接的智能体使用。

5. 引导你的大脑

运行附带的引导访谈以构建全面的工作档案：

# Paste the contents of BootstrapPrompt.txt into a fresh AI conversation
# The agent will interview you across 10 sections and produce a structured profile

面向高级用户的 CLI

BHGBrain 包含一个完整的 CLI 用于直接管理：

bhgbrain search "authentication patterns" --mode hybrid
bhgbrain list --limit 20
bhgbrain category set "Coding Standards" --file ./standards.md
bhgbrain stats
bhgbrain gc --consolidate    # Merge similar memories, flag stale ones
bhgbrain backup create

何时使用 BHGBrain 与 MEMORY.md

MEMORY.md 适用于单个智能体在单个项目上用少量笔记的情况。BHGBrain 适用于团队、多智能体工作流，以及任何 AI 记忆需求已超出文本文件范围的人。

下一步

BHGBrain v1 专注于把核心做对：可靠的存储、智能去重、混合搜索和多客户端访问。路线图包括：

• 多用户 RBAC —— 团队级访问控制
• 静态加密 —— 面向受监管环境
• 云同步 —— 可选的跨机器同步
• 工作记忆 TTL —— 自动过期的临时草稿记忆

试试看

BHGBrain 是开源的，采用 MIT 许可证。

GitHub： github.com/Big-Hat-Group-Inc/BHGBrain

如果你的 AI 智能体总是忘记你昨天告诉它们的内容，给它们一个能持久的大脑吧。

Kevin Kaminski 是 Big Hat Group 的创始人，我们在那里围绕企业 AI、Windows 365 和云基础设施构建工具和咨询实践。BHGBrain 源于我们自己在日常多智能体工作流中对智能体失忆的沮丧。