BrainKeeper

"One who truly knows you"

Personal Cognitive Substrate — 跨项目、跨 session 的第二大脑

Quick Install

curl -fsSL https://raw.githubusercontent.com/CtriXin/brainkeeper/main/install.sh | bash

Install via AI Agent

Paste this single line into Claude Code / Cursor / Codex — the agent will handle the rest:

Install BrainKeeper MCP server by running: curl -fsSL https://raw.githubusercontent.com/CtriXin/brainkeeper/main/install.sh | bash — it handles everything including MCP config. Restart the client after install.

What is BrainKeeper?

BrainKeeper 是一个 MCP server，为 AI coding agent 提供持久化的知识层：

传统 AI：  Session → Forget → Session → Forget
Memory：  Session → Store → Recall → Session
BrainKeeper： Session → Learn → Cross-Project Recall → Evolve

核心差异化价值：

Recipe — 结构化的实现经验，带触发词匹配，跨项目复用
Board — 四象限看板 + 备忘，项目级任务管理
Thread — 上下文蒸馏，跨 session 恢复工作状态
主动推送 — bootstrap 时自动匹配相关经验，不需手动查询

Workflow Overview

This repo keeps the public flow in Mermaid so open-source history does not accumulate HTML/PNG card assets.

flowchart LR
  subgraph Entry[Entry Surfaces]
    A["AI clients\nClaude / Codex / Cursor"]
    B["bin/dst + hooks\nbootstrap / token monitor"]
    C["Resources\nrecipe index / thread list"]
  end
  subgraph Runtime[Core Continuity Loop]
    D["brain_bootstrap\nload repo rules + git context"]
    E["Recall\nrecipes + boards + best thread"]
    F["Capture\ncheckpoint / fragment / issue sync"]
    G["Persist\n~/.sce + repo Session Index"]
    H["Resume\nnext session gets next action fast"]
  end
  subgraph Artifacts[Durable Artifacts]
    I["brain/\nindex.json + recipes/*.md"]
    J["threads / fragments /\nissue-links / boards"]
    K["repo/.ai/SESSION_INDEX.md"]
  end
  A --> D
  B --> D
  C --> E
  D --> E --> F --> G --> H
  G --> I
  G --> J
  G --> K

Installation

One-line Install (Recommended)

curl -fsSL https://raw.githubusercontent.com/CtriXin/brainkeeper/main/install.sh | bash

This clones BrainKeeper to ~/.local/share/brainkeeper, installs dependencies, and prints the MCP config to add.

Manual Install

git clone https://github.com/CtriXin/brainkeeper.git ~/.local/share/brainkeeper
cd ~/.local/share/brainkeeper
npm install --production

dist/ is pre-built in the repo — no build step needed.

Update

cd ~/.local/share/brainkeeper && git pull && npm install --production
# Or:
curl -fsSL https://raw.githubusercontent.com/CtriXin/brainkeeper/main/install.sh | bash -s -- --update

The CLI checks npm for a newer release at most once every 24 hours and prints a short update hint when a newer brainkeeper version is available. Disable it with:

export BRAINKEEPER_NO_UPDATE_CHECK=1

Install a specific tag or branch

curl -fsSL https://raw.githubusercontent.com/CtriXin/brainkeeper/main/install.sh | bash -s -- --ref v2.4.1
curl -fsSL https://raw.githubusercontent.com/CtriXin/brainkeeper/main/install.sh | bash -s -- --ref main

MCP Configuration

Add to your MCP config file:

Client	Config File
Claude Code	`~/.claude/settings.json`
Cursor	`.cursor/mcp.json`
Windsurf	`.windsurfrules/mcp.json`

{
  "mcpServers": {
    "brainkeeper": {
      "command": "node",
      "args": ["~/.local/share/brainkeeper/dist/server.js"]
    }
  }
}

Note: Replace ~ with your actual home directory path if your client doesn't expand ~. Example: "/Users/yourname/.local/share/brainkeeper/dist/server.js"

MMS (Isolated Environment) Notes

MMS rewrites HOME to an isolated session path. BrainKeeper's install script auto-detects this and installs to your real home directory so the installation persists across sessions.

Symlink issues: MMS may not support symlinks by default. The install script uses npm (not pnpm) to avoid this. If you must use pnpm:

echo 'node-linker=hoisted' >> ~/.local/share/brainkeeper/.npmrc
cd ~/.local/share/brainkeeper && pnpm install

MCP Tools

Knowledge — 知识管理

工具	用途
`brain_learn`	从完成的任务中提取可复用 recipe，持久化到知识库
`brain_recall`	根据任务描述查找相关 recipe，返回步骤/文件/坑点
`brain_list`	列出所有 recipe 摘要（支持按 project/tag/framework 过滤）

Distill — 上下文蒸馏

工具	用途
`brain_bootstrap`	轻量启动入口 — board 信号 + thread 恢复 + recipe 自动推送
`brain_checkpoint`	蒸馏当前工作状态，写入 thread 文件供跨 session 恢复
`brain_fragment`	记录一个连续工作片段，适合开发/探索/debug/修复过程中随时留痕
`brain_link_issue`	把当前 thread chain 的 root 显式绑定到一个 `issue-tracking` issue slug
`brain_sync_issue`	把当前 thread chain 的 digest 同步到 `issue.md` 的固定 Mindkeeper 区块
`brain_threads`	列出所有未过期的 thread，按 repo 分组

brain_checkpoint 还会为当前项目维护一份本地 Session Index：

路径：<repo>/.ai/SESSION_INDEX.md
字段：time / cli / model / folder / task / status / thread id
作用：同一项目开很多窗口后，直接进项目目录就能看出最近 distill 过什么、该恢复哪个 dst-...
回填：bk dst sync 可根据现有 thread 重建当前项目索引

brain_fragment 和 brain_checkpoint 的边界：

brain_fragment：小步留痕。每做完一段开发、探索、debug、修复就追加一条，不要求立刻蒸馏。
brain_checkpoint：阶段压缩。把当前阶段沉淀成新的 dst-* 快照，供跨 session 恢复。
两者不冲突：同一条任务链会共享一个 root，新的 checkpoint 仍能看到此前 fragments。

brain_link_issue / brain_sync_issue 的使用方式：

先设置环境变量：BRAINKEEPER_ISSUE_TRACKING_ROOT=/path/to/issue-tracking
第一次绑定：调用 brain_link_issue(repo, issue, project?)
需要归档时：调用 brain_sync_issue(repo, thread?)
当前实现是显式同步，不会每写一条 fragment 就自动刷 issue.md

Board — 项目看板

工具	用途
`brain_board`	读写项目四象限看板（紧急/重要矩阵）+ 备忘
`brain_check`	扫描所有项目信号（deadline/overdue/stale）+ recipe 健康

Storage

所有数据存储在 ~/.sce/ 下：

~/.sce/
├── brain/
│   ├── index.json          # Recipe 索引（快速查找）
│   └── recipes/*.md        # Recipe 文件（frontmatter + markdown）
├── threads/                # Thread 蒸馏文件（dst-YYYYMMDD-*.md）
├── fragments/              # Thread 链下的持续工作片段（<root>.jsonl）
├── issue-links/            # root -> issue-tracking 显式映射（<root>.json）
└── boards/                 # Board JSON 文件（每个项目一个）

项目目录内会按需生成：

<repo>/.ai/SESSION_INDEX.md  # 项目内 session/thread 索引，便于 crash 后找回

Recipe 格式

---
id: ad-lazy-load
triggers: ["广告延迟加载", "ad lazy load"]
summary: Vue3 广告延迟加载 hook
framework: vue3
project: ptc_ssr_crypto
confidence: 0.9
tags: ["ads", "intersection-observer"]
---
## 实现步骤
1. 创建 useAdLazyLoad composable
2. ...

## 涉及文件
- `src/composables/useAdLazyLoad.ts` — 核心 hook

## 已知坑点
- iOS Safari IntersectionObserver 需要 polyfill

## Changelog
- 2026-03-27: 首次记录

Recipe 归档约定

BrainKeeper 默认不鼓励把每一条零散经验都拆成新 recipe。推荐按下面的边界维护：

新建 recipe：这个经验已经是稳定流程，未来会高频复用，而且单独 recall 会更清楚。
并入已有 recipe：这个经验只是同一主题下的新补充，拆出去只会让知识变散。

建议优先按 3 类归属：

全局工具 recipe：跟具体项目无关，跨项目都会反复遇到。例子：lark-cli、Feishu 表格定位、隔离 HOME、MMS 启动环境。
项目 recipe：只属于某个项目的结构、流程、坑点。例子：某个 repo 的页面骨架、默认 bug 表、静态注入规则。
临时 thread / board 信息：还没有稳定成方法论，只是这一次任务的上下文或提醒。

可以用下面的判断顺序：

这条经验未来会不会在多个项目里重复出现？
它是不是已经形成固定排查顺序或命令模板？
单独建一个 recipe 会不会比塞进现有 recipe 更好找？

如果 1 和 2 都是"是"，通常应该新建。如果只有局部补充价值，通常应并入已有 recipe。

当前推荐的治理方式：

rcp-brainkeeper-*：BrainKeeper 自身工作流与跨项目规则
rcp-lark-*：Feishu / lark-cli / 表格查改流程
rcp-mms-env-*：隔离环境 / HOME / 启动问题
rcp-<project>-*：某个具体项目的业务经验

一个实用原则：

高频、跨项目、稳定复用 → 新建
项目专属、不会外溢 → 放项目 recipe
零散补充、还不稳定 → 先并入已有 recipe 或留在线程/看板

Thread 格式

---
id: dst-20260327-abc123
repo: /path/to/your-project
task: 修复登录Bug
branch: fix/login
parent: dst-20260326-xyz789
cli: codex
model: gpt-5.4
folder: src/auth
created: 2026-03-27T15:08:38.729Z
ttl: 7d
---
## 决策
- 用 JWT 替换 session cookie

## 变更
- auth.ts
- middleware.ts

## 待续
- [ ] 部署验证

## 当前状态
JWT 替换完成，待部署

Key Features (v2.1)

Recall 语义匹配

55+ 同义词组（前端/后端/DevOps/通用）
Trigram 模糊匹配（精确匹配失败时 fallback）
Tags 参与评分
CamelCase/kebab-case 自动拆分 + 30+ 缩写展开

Bootstrap 自动推送

brain_bootstrap 冷启动时自动用 task 描述匹配 recipe
输出 ≤3 条摘要提示，不需手动调 brain_recall
不更新访问统计，避免污染衰减信号

Recipe 衰减 & 遗忘

90+ 天未访问 / confidence < 0.7 / 框架过时 → 标记 ⚠️
brain_check 时自动降权：accessCount=0 且 180+ 天 → confidence=0.3
brain_list 显示健康摘要（活跃/过时/已降权）

Board-Thread-Recipe 三域关联

brain_checkpoint 回执显示关联 board items
Board item 标 done 时提示提取 recipe
brain_learn 自动关联匹配的 board item

Board 僵尸检测

active 但 90+ 天未更新的 item → brain_check 中显示 💤 信号

Architecture

src/
├── server.ts      # MCP server 入口 + tool handlers
├── router.ts      # 语义路由（同义词/trigram/tags 匹配）
├── storage.ts     # 文件 I/O（recipe/board CRUD + 衰减/关联）
├── bootstrap.ts   # Thread 解析/恢复/列表
├── distill.ts     # Checkpoint 蒸馏 pipeline
├── fragments.ts   # root 级 append-only worklog
├── issue-sync.ts  # issue link / digest sync
├── types.ts       # 所有 TypeScript 类型定义
└── env.ts         # 环境检测（MMS bridge session → 真实 HOME）

Development

# Clone for development
git clone https://github.com/CtriXin/brainkeeper.git
cd brainkeeper
pnpm install
pnpm build

# Run MCP server (dev mode with hot reload)
pnpm dev

# CLI
pnpm cli list
pnpm cli search "广告延迟加载"

# Tests
pnpm test

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 57 Commits
bin		bin
dist		dist
docs		docs
hooks		hooks
scripts		scripts
src		src
test		test
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
PROJECT_CARD.md		PROJECT_CARD.md
README.md		README.md
TODO.md		TODO.md
install.sh		install.sh
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

BrainKeeper

Quick Install

Install via AI Agent

What is BrainKeeper?

Workflow Overview

Installation

One-line Install (Recommended)

Manual Install

Update

Install a specific tag or branch

MCP Configuration

MMS (Isolated Environment) Notes

MCP Tools

Knowledge — 知识管理

Distill — 上下文蒸馏

Board — 项目看板

Storage

Recipe 格式

Recipe 归档约定

Thread 格式

Key Features (v2.1)

Recall 语义匹配

Bootstrap 自动推送

Recipe 衰减 & 遗忘

Board-Thread-Recipe 三域关联

Board 僵尸检测

Architecture

Development

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages