obsidian-knowledge-brain v4.0 / Obsidian 知识大脑 v4.0
An AI agent skill that remembers every technical decision and bug fix across your sessions — and learns from them. 一个让 AI Agent 跨会话记住技术决策和错误修复、并自动学习的技能。
Every time you debug an error with an AI agent, that knowledge vanishes when the session ends. obsidian-knowledge-brain captures it — automatically building a searchable knowledge base that evolves project rules over time. Like a project librarian that learns from every conversation.
每次和 AI 编程解决了 bug、做了技术决策，下次对话就忘了。obsidian-knowledge-brain 帮你记住——自动构建可检索的知识库，持续进化项目规则。一个从每次对话中学习的项目图书管理员。
v2.0 → v3.0: What Changed / 演进
v2.0 required an Obsidian vault, Python cron scripts, and Claude Code hooks. It was powerful but heavy — 11 Python scripts, a vault directory tree, and tight coupling to one platform.
v2.0 需要 Obsidian vault、Python 定时脚本、Claude Code hooks。强大但沉重——11 个 Python 脚本、一整套 vault 目录树、绑定单一平台。
v3.0 is a skill-only system. / v3.0 是纯技能系统。 No vault. No scripts. No cron daemon. It works purely through the AI Agent reading and writing .md files in your project's .claude/ directory. 无 vault。无脚本。无守护进程。Agent 直接在项目 .claude/ 里读写 .md 文件执行全部逻辑。
| v2.0 | v3.0 | |
|---|---|---|
| Storage / 存储 | External Obsidian vault | .claude/ inside your project / 项目内 .claude/ |
| Execution / 执行 | Python scripts + hooks | AI Agent reads/writes markdown / Agent 读写 markdown |
| Dependencies / 依赖 | Python 3.10+, PyYAML, requests | None (Agent-native) / 零依赖 |
| Platforms / 平台 | Claude Code only | CC, Cursor, Gemini CLI, Codex |
| Obsidian | Required vault / 必须 | Optional visual browser / 可选浏览 |
| Bootstrap / 播种 | setup.py interactive | Agent auto-detects + plans / Agent 自动诊断+规划 |
The core idea is the same — [DECISION] and [ERROR] annotations → MECE classification → pattern extraction → rule evolution. But v3.0 makes the Agent the executor, not a Python pipeline.
核心思路不变：[DECISION] 和 [ERROR] 标注 → 互斥穷尽分类 → 模式提取 → 规则进化。但 v3.0 让 Agent 成为执行者，而非 Python 流水线。
v3.0 → v4.0: What Changed / 演进
v3.0 solved v2.0's "second brain bloat" by making knowledge project-local. The trade-off: knowledge learned in one project never transfers to another. v3.0 解决了 v2.0 的臃肿，但知识被困在单个项目里。
v4.0 adds global cross-project knowledge / v4.0 增加了跨项目全局知识：
- Global Atom Table / 全局原子表 —
~/.obsidian-knowledge-brain/atoms.json, cap ≤20 active atoms, root-cause hash dedup - Promotion / 晋升 — Same error in ≥2 independent projects → human confirms → promoted to global table
- Pre-Action Triggers / 预行动触发器 — Pre/During/Post three-phase MUST instructions injected into always-loaded file
- Demotion Lifecycle / 降级生命周期 — 365 days no trigger → auto-flag, 90-day sync window → delete
- Cross-Platform / 跨平台 — Tier 1 Claude Code full auto (hooks), Tier 2 Cursor/Gemini/Codex (pre-action auto)
| v3.0 | v4.0 | |
|---|---|---|
| Knowledge sharing / 知识共享 | Project-local only | Local + global atoms (≤20) |
| Pre-action | Rule table (growing) | Fixed MUST + 3-phase + debounce |
| Cross-project learning | None | Recurrent pitfalls only (signal) |
| Global path | None | ~/.obsidian-knowledge-brain/ |
| Uninstall | Manual | --uninstall + .uninstalled marker |
Installation / 安装
Claude Code (全自动 / full auto)
git clone https://github.com/Tubo2333/obsidian-knowledge-brain.git .claude/skills/obsidian-knowledge-brain/
That's it. The Agent auto-loads the skill on next session start. / 搞定。Agent 下次启动自动加载。
For optional hook automation (T1/T2/T3), add to settings.json: / 可选钩子自动化：
{
"hooks": {
"SessionStart": [{ "command": "python .claude/skills/obsidian-knowledge-brain/scripts/session_start.py" }],
"Stop": [{ "command": "python .claude/skills/obsidian-knowledge-brain/scripts/session_close.py --prompt" }]
}
}
Cursor / Gemini CLI / Codex (手动触发 / manual trigger)
Copy the obsidian-knowledge-brain/ folder into your platform's skill directory. / 把 obsidian-knowledge-brain/ 复制到对应平台目录：
| Platform / 平台 | Target directory / 目标目录 |
|---|---|
| Cursor | .cursor/skills/obsidian-knowledge-brain/ |
| Gemini CLI | .gemini/extensions/obsidian-knowledge-brain/ |
| Codex | .codex/skills/obsidian-knowledge-brain/ |
Replace .claude/ paths in SKILL.md with your platform's base. Then type commands manually — the Agent reads SKILL.md and executes protocols on your trigger words. See references/platform-guide.md. / 把 SKILL.md 中 .claude/ 替换为对应目录，然后输入触发词手动执行。
Quick Start in Four Words / 四个词上手
| Trigger / 触发词 | What it does / 效果 |
|---|---|
诊断 / diagnose | Scan project, report chaos score, propose a plan — no files touched / 扫描项目，输出混沌度评分和规划，不碰文件 |
整理项目 / bootstrap | Build .claude/rules/ + .claude/projects/ + .claude/memory/ skeleton / 创建框架骨架 |
收尾 / wrap up | End of session: save decisions, errors, update project status / 会话结束：保存决策、错误、更新项目状态 |
健康检查 / health check | Full 7-dimension scan: ceiling, contradictions, orphans, GC / 七维全量扫描 |
Work normally. / 正常干活。 The skill captures knowledge from your flow — not by interrupting it. / 知识在你工作中被捕获——而不是打断你来问。
Cost / 花费
Zero monetary cost. / 零费用。 This is a set of markdown templates and Agent protocols — no API calls, no servers, no subscription. 纯 markdown 模板和 Agent 协议——无 API 调用、无服务器、无订阅。
The "cost" is / "花费"的是时间：
- ~5-10 minutes for first bootstrap (Agent reads/writes ~15 files) / 首次播种约 5-10 分钟
- ~2 minutes per session end for "收尾" wrap-up / 每次收尾约 2 分钟
- ~50-200 lines added to your
.claude/directory per session / 每次会话增加 50-200 行
Token usage: approximately 3,000-8,000 tokens per session for annotation and classification. Comparable to reading a few extra files. / Token 消耗：每次会话约 3,000-8,000 tokens，相当于多读几个文件。
Obsidian Integration (Optional) / Obsidian 集成（可选）
v4.0 stores knowledge as plain .md files in your agent directory. To browse as a knowledge graph: / v4.0 用纯 .md 存储知识，要用 Obsidian 浏览知识图谱：
- Open your project folder as an Obsidian vault / 用 Obsidian 打开项目文件夹
- The
.claude/directory becomes a browsable wiki /.claude/目录变成可浏览的 wiki [[wikilinks]]between decisions, pitfalls, and rules render as graph edges / 决策、陷阱、规则之间的[[双向链接]]呈现为图谱边
No plugin needed. The folder-is-vault convention works with any Markdown editor — Obsidian just makes the cross-references visual. / 无需插件。文件夹即 vault 的约定适用于任何 Markdown 编辑器——Obsidian 只是把交叉引用可视化。
What's Inside / 目录结构
obsidian-knowledge-brain/
├── SKILL.md ← Agent skill definition / 技能定义 (≤200 lines, always loaded)
├── README.md ← This file / 本文件
├── LICENSE ← MIT
├── description.md ← Marketplace listing / 技能市场描述 (≤500 chars)
├── templates/ ← 4 templates for rules, projects, pitfalls, decisions / 4 个模板
│ ├── rule.template.md
│ ├── project.template.md
│ ├── pitfall.template.md
│ └── decision.template.md
├── references/ ← 10 protocol & seed data files / 10 个协议和种子数据 (each ≤80 lines)
│ ├── quickstart.md ← 5-minute walkthrough / 5 分钟上手
│ ├── platform-guide.md ← Cursor/Gemini/Codex setup / 平台适配指南
│ ├── troubleshooting.md ← Common recovery scenarios / 常见故障排查
│ ├── domain-registry.md ← Rule domain vocabulary for bootstrap / 规则域注册表
│ ├── error-taxonomy.md ← Error type vocabulary (50+ types) / 错误分类法
│ ├── root-cause-kb.md ← Known root cause → symptom lookup / 根因知识库
│ ├── phase-a-bootstrap.md ← Framework skeleton builder protocol / 框架播种协议
│ ├── t1-session-start.md ← Session start 5-step protocol / 会话启动协议
│ ├── t2-session-end.md ← Session end close protocol / 会话结束协议
│ └── t3-periodic-check.md ← Weekly health check 7-dim scan / 定期健康检查
└── scripts/ ← 20 Python scripts (v4.0 core + v3.0 hooks + v2 utilities)
├── global_atoms.py ← NEW v4.0: atom table CRUD + promotion/demotion
├── keyword_index.py ← NEW v4.0: safe merge sync + .bak protection
├── pre_action.py ← NEW v4.0: format detect + instruction injection
├── install.py ← REWRITTEN v4.0: 9-step idempotent installer
├── session_start.py ← T1 hook: SessionStart briefing / 会话启动简报
├── session_close.py ← T2 hook: session-end prompt + validator / 收尾协议+验证
├── session_harvester.py ← Hook transcript harvester / 会话转录收割器
├── runner.py ← Pipeline orchestrator (5-step) / 管道编排器
├── analyzer.py ← Root-cause analysis (keyword + LLM) / 根因分析
├── maintainer.py ← Rule lifecycle + merge detection / 规则维护
├── reporter.py ← Weekly reports + index rebuild / 周报+索引重建
├── compiler.py ← CLAUDE.md index sync / 索引同步
├── backup.py ← JSONL transcript backup / 会话备份
├── config.py ← Configuration loader / 配置加载器
├── setup.py ← Interactive vault setup (v2 legacy) / 交互式安装 (v2 遗留)
├── validate_frontmatter.py ← Frontmatter field validation / 元数据字段校验
├── link_validator.py ← Wiki-link integrity checker / 双向链接完整性检查
├── score_sessions.py ← Session scoring utility / 会话评分工具
├── reformat_tables.py ← Table reformatter / 表格格式化
└── config.example.yaml ← Sample configuration / 配置示例
FAQ / 常见问题
Q: Does this need Obsidian? / 需要 Obsidian 吗？ A: No. v4.0 stores everything in your agent directory. Obsidian is an optional viewer. / 不需要。v4.0 数据全在项目 agent 目录里，Obsidian 只是可选查看器。
Q: Does it work without Claude Code? / 不用 Claude Code 能用吗？
A: Yes — Cursor, Gemini CLI, and Codex all work via manual trigger words. See references/platform-guide.md. / 能——输触发词手动执行即可。
Q: How long until it's useful? / 多久见效？ A: ~3 sessions × ~7 annotations → 20 total → pattern extraction activates. Before that, everything is still stored — just no auto-detection yet. / 约 3 次会话积累 20 条标注后模式提取激活。在此之前知识照常存储，只是还没自动检测规律。
Q: Does it call external APIs? / 会调用外部 API 吗？ A: No. All classification is deterministic (MECE rules + heuristic matching). LLM-based pattern extraction is an optional Tier 2 feature gated behind explicit human opt-in. / 不会。全部分类是确定性的（MECE 规则 + 启发式匹配）。LLM 模式提取是可选的 Tier 2 功能，需人工显式激活。
Q: What's the global atom table? / 什么是全局原子表？
A: ~/.obsidian-knowledge-brain/atoms.json stores up to 20 cross-project knowledge atoms. When the same error occurs in 2+ projects, it's promoted here so every project benefits. / 存储最多 20 条跨项目知识原子，同一错误在 2+ 项目中复现时晋升到此。
License / 许可证
MIT — use it, modify it, distribute it freely. / MIT — 随意使用、修改、分发。