Obsidian Knowledge Brain v4.0 / Obsidian 知识大脑 v4.0

Schema: 4.0 | Lines: ≤200 | Load: Always (if skill active) Platforms: Claude Code — full auto (hooks + cron). Cursor / Gemini CLI / Codex — manual trigger (type "收尾" to save, "诊断" to bootstrap). Requires an AI Agent with file read/write. Not designed for plain-terminal or Agent-free use. / CC 全自动，其他平台需手动输入口令触发。

Upgrade from v2.0: zero vault dependency (无 vault 依赖), project-local .claude/ storage. Obsidian is now optional — open your project folder as a vault for knowledge graph visualization. / Obsidian 现为可选——将项目文件夹作为 vault 打开即可获得知识图谱可视化。

What this does / 它做什么: Every time you debug an error or make a technical decision with an AI agent, that knowledge vanishes when the session ends. This skill remembers — it captures your decisions and error fixes across sessions, builds a searchable knowledge base, and evolves project rules automatically. A personal project librarian that learns from every conversation. / 每次和 AI 编程解决了 bug、做了技术决策，下次对话就忘了。这个 Skill 帮你记住——自动捕获每次会话的决策和错误，构建可检索的知识库，持续进化项目规则。一个从每次对话中学习的项目图书管理员。

Obsidian? Not required. v4.0 stores knowledge as .md files in your agent directory. Open your project as an Obsidian vault to browse the knowledge graph — purely optional. See §0a. / 非必需。用 Obsidian 打开项目文件夹即可浏览知识图谱——完全可选。

→ First time? See references/quickstart.md (5-minute walkthrough / 5分钟上手).

0. Critical Rules / 关键规则 (Priority 0)

v4.0 dual rule / 双规则:

1. [ERROR:] stubs — IMMEDIATE after fix / 修复后立即记录。 After resolving ANY error, BEFORE writing the permanent fix, append a one-line stub to memory/_phase1_inbox.md: [ERROR: type=<from-taxonomy> | resolution=<fix> | project: <slug>] This is the FINAL step of every error fix. NOT deferred to session end. Skipping this and hitting the same error again → [ERROR: type=missed-record | error_type=<type>].

2. [DECISION:] annotations — session end only / 仅会话结束时。 Do NOT interrupt work to annotate decisions mid-session. Work normally. At session end (T2 "收尾"), extract ALL technical decisions from the session transcript into [DECISION:] format. This is a memory system — it learns from completed experiences, not live interruptions.

Format: [DECISION: <summary> | context: <why> | project: <slug> | scope: project|cross-project] and [ERROR: type=<from-taxonomy> | resolution=<fix> | project: <slug>]. Missing required fields → mark # MVA_FAIL:<field> and leave in inbox.

0a. Prerequisites / 环境要求

Required / 必需: An AI Agent platform (Claude Code, Cursor, Gemini CLI, Codex) with file read/write capability + a project directory. / 一个有文件读写能力的 AI Agent 平台 + 一个项目目录。

Recommended / 推荐: Python 3.x (for hook scripts; all protocols work manually without it) + Git (version-control your knowledge base). / Python 3.x（钩子脚本）+ Git（版本控制）。

Obsidian? Not required. v4.0 stores knowledge as plain .md in your agent directory. Open your project folder as an Obsidian vault to browse the knowledge graph — purely optional. v2.0 users: old vault data preserved in archive/. / 非必需。v4.0 用纯 .md 存储，用 Obsidian 打开项目文件夹即可浏览知识图谱——完全可选。

0b. Sandbox Boundary / 沙箱边界

Project scope / 项目范围: This skill reads and writes within <project>/{AGENT_DIR}/ and <project>/archive/. No other project directories are modified. / 仅触碰项目内的 Agent 目录和 archive/。

Global store / 全局存储 (v4.0): ~/.obsidian-knowledge-brain/ — a single, well-known directory outside the project. Contains atoms.json (global atom pointer table, ≤20 active atoms), atoms.json.bak (write-backup), and atoms.json.lock (concurrent write guard). Written ONLY during install/uninstall/promotion. During normal Agent sessions, atoms.json receives ONLY last_triggered timestamp updates when atoms are matched (metadata, not knowledge modification). All other writes are promotion-only. Read during Pre-action sync. No other paths outside the project are touched. / 全局存储目录，仅在安装/卸载/晋升时写入，正常会话只更新 last_triggered 时间戳。

Uninstall / 卸载: --uninstall flag creates .uninstalled marker → Pre-action instruction removed from always-loaded file → _global_atoms removed from keyword index → atoms.json preserved (user may reinstall). / 卸载时保留 atoms.json 以备重新安装。

0c. Known Limitations / 已知局限 (Agent: read before acting)

L1 — Pre-action is MUST, not hook. You are responsible for executing Pre/During/Post steps from the injected instruction. Skip Pre + hit documented pitfall → [ERROR: type=missed-atom | atom_id=<id>]. Skip Post error recording → [ERROR: type=missed-record | error_type=<type>].

L2 — Gemini CLI / Codex always-loaded files unverified. .gemini/extensions.json and .codex/codex.yaml are listed but NOT tested. On these platforms, verify the file is actually loaded by your platform. If not → read ~/.obsidian-knowledge-brain/atoms.json directly.

L3 — JSON array-top-level not supported for injection. pre_action.py assumes { object-top-level. Unreachable in practice (all known platforms use Markdown/YAML/plain). If encountered → skip injection, note it.

L4 — install.py version mismatch warns but doesn't exit. If SKILL.md schema ≠ install.py version → stop, ask user to resolve.

L5 — Cross-machine atoms.json is manual. Each machine has its own ~/ atoms.json. Machines converge: same root_cause_id → same content-hash atom ID. To sync manually, copy ~/.obsidian-knowledge-brain/atoms.json.

L6 — Dual-platform: shared atoms.json, independent keyword indexes. If .claude/ + .cursor/ coexist → run install.py for each. Pre-action does NOT auto-appear in both.

L7 — Non-CC platforms: T1/T2/T3 are manual. Pre-action still auto (in always-loaded file). But session-start, "收尾", "健康检查" require user trigger words. Remind user at appropriate moments.

L8 — Pointer drift. Atom pointers (rules/foo.md#L6-L8) may go stale. Pre-action: lines mismatch topic → load entire file. T3: file missing → flag pointer_broken: true. Not auto-repaired — note drift for next T2/T3.

L9 — Recovery from _global_atoms loses metadata. Both atoms.json + .bak corrupt → rebuild from _global_atoms. Recovers IDs/types/phases/pointers/triggers. Loses project_origin (→[current]), promoted (→now), demoted (→false). T3 flags as "recovered, needs review."

Platform Matrix / 平台矩阵

○ = remind user.

1. Phase Detection / 相位检测 (Execute FIRST)

Check .claude/PHASE_A_COMPLETE:

• Exists + status: complete + bootstrap_date ≤90 days → Phase B (skip bootstrap)
• Exists + status: complete + >90 days → re-validate 6 checklist items; pass→refresh date; fail→re-diagnose
• Exists + status: in_progress → re-run all 6 checks (marker only stores overall result, no per-item state)
• Corrupt YAML / missing fields → re-diagnose

3-axis check: .claude/rules/ (≥8 valid-frontmatter files?) + .claude/projects/ (≥1?) + .claude/memory/ (pitfalls/ decisions/ preferences/ reference/ subdirs?). 3 green → Phase B. Any yellow/red → Phase A incremental. 2+ red → Phase A full bootstrap.

2. Phase A · Framework Bootstrap / 框架播种

→ Full instructions: references/phase-a-bootstrap.md

Summary: Diagnose chaos score (混沌度 0-12) → legacy automation audit (遗留自动化审计, reduced if chaos≤3) → classify raw content (parallel 3-tag labeling: IS_RULE/IS_PROJECT/IS_MEMORY) → build skeleton (CLAUDE.md + rules/ + projects/ + memory/) → migrate originals to archive/ → validate 6-item checklist → create PHASE_A_COMPLETE marker.

3. T1-T4 Trigger Contracts / 触发契约

T1 · Session Start / 会话启动 (Required)

→ references/t1-session-start.md

5-step protocol: crash detection → T2 completion guard → inbox drain (MECE classify ALL annotations, always; pattern extraction gated by cold-start counter) → health summary → project briefing (≤30 lines, bilingual). Writes .session_active new marker.

T2 · Session End / 会话结束 (Required)

→ references/t2-session-end.md

Safety net: F2 PRIMARY (user says "收尾" — the ONLY guarantee on all platforms). F1 auto on CC only. F4 catches crashes from inbox residue. No F3 (auto-checkpoint has no implementation — LLMs cannot count their own tool calls). Phase 1 quick close (① decisions ② errors ③ status ④ rule trigger update ⑤ ceiling check). Phase 2 deferred (⑥ rules created ⑦ rules outdated). MVA check before write. Anti-pollution. Delete .session_active. Emit [SESSION_SUMMARY].

T3 · Periodic Health Check / 定期健康检查 (Recommended)

→ references/t3-periodic-check.md

Trigger: L1 cron / L2 T1 detects >7 days / L3 user口令. Concurrent guard: skip if .session_active present. 7-dim scan (hard ceiling, contradiction, orphan, GC, pattern extraction Tier 1→2→3, index rebuild, legacy back-pressure). Tier 2 default OFF. ROI tracking: hit_rate = 0 × 30 days → auto-degrade to cold-start.

T4 · Manual Invoke / 手动调用 (On-demand)

4. Annotation MVA Standards / 标注最低可行标准

Quality target: ≥90% field completeness. 3 consecutive sessions <90% → T3 warns.

Anti-pollution (反污染): ① [DECISION:] store only FINAL adopted solutions, never dead-end explorations. ② [ERROR:] only FIXED errors; UNRESOLVED → inbox. ③ No intermediate states (不存中间态): temporary judgments, unverified hypotheses → do NOT annotate. ④ No duplicates: same type+root_cause_id → increment sessions_observed counter, no new file.

5. Cold Start Protocol / 冷启动协议

memory/ empty or mode: cold_start: classify+store only, no pattern extraction. Counter in _phase1_inbox.md YAML frontmatter (cold_start: {total_annotations, sessions_observed, threshold: 20, mode}). ≥20 annotations AND ≥3 sessions → switch mode: active, announce transition.

6. File Manifest / 文件清单

<templates/> 4 files     → Agent uses these to create rules/projects/pitfalls/decisions
<references/> 10 files   → Agent loads on-demand per trigger/phase (each ≤80 lines)
  ├── Seed data:    error-taxonomy.md, root-cause-kb.md, domain-registry.md
  ├── Protocols:    t1-session-start.md, t2-session-end.md, t3-periodic-check.md
  ├── Bootstrap:    phase-a-bootstrap.md
  ├── User guides:  quickstart.md, platform-guide.md, troubleshooting.md
SKILL.md                 → Always loaded (≤200 lines)

7. Install & Config / 安装与配置

Where to put files / 文件放哪里

Copy obsidian-knowledge-brain/ into <project>/.claude/skills/. For non-Claude-Code platforms, run: python scripts/install.py --platform cursor (or gemini, codex). This replaces all .claude/ paths with your platform's base directory. / 复制到 skill 目录后，非 CC 平台运行 python scripts/install.py --platform cursor 一键替换路径。

Hook config (Claude Code only, optional) / 钩子配置

Claude Code settings.json:

• SessionStart → session_start.py (T1)
• Stop → session_close.py --prompt (T2)
• CronCreate weekly → maintainer.py --health-check (T3)

No-hook / no-Agent fallback / 无钩子降级

If your platform has no hooks or no Agent: T1 via manually reading SKILL.md §0. T2 via typing "收尾" / "wrap up". T3 via typing "健康检查" / "health check". F3 auto-checkpoints still work if your Agent supports them. Core knowledge capture works even without hooks. / 即使没有钩子，核心知识捕获仍可通过口令手动触发。

English-only users / 纯英语用户

All labels and headings are bilingual (Chinese + English). If you read only English, the / 中文 suffix is a term annotation — you can ignore it. The body text is English-primary. See §8 for term translations if curious. / 所有标签中英双语，纯英语读者可忽略 / 中文 后缀，正文以英语为主。

v4.0 Global Atom Table / 全局原子表

The global atom table lives at ~/.obsidian-knowledge-brain/atoms.json. It is created automatically by install.py or Phase A bootstrap. Cross-project knowledge is promoted here when the same error occurs in ≥2 independent projects. See references/t2-session-end.md §②b for promotion protocol. / 全局原子表位于 ~/.obsidian-knowledge-brain/atoms.json，同一错误在 ≥2 个独立项目中复现时晋升到此。

8. FAQ / 常见问题

Q: Nothing happens when I install. / 安装后没反应。 A: Agent auto-loads and runs §1. No Agent → manually follow §0 and §3. The skill is a protocol, not a daemon. More recovery scenarios: references/troubleshooting.md.

Q: Why .claude/? I use Cursor. / 为什么是 .claude/？ A: Replace with .cursor/ (see references/platform-guide.md). The folder name is convention — structure works on any platform.

Q: How long until useful? / 多久见效？ A: ~3 sessions × ~7 annotations → 20 total → pattern extraction activates. Before that, everything is still stored — just no auto-detection yet.

Q: Can I use this without any Agent? / 没 Agent 能用？ A: No. This skill requires an AI Agent to execute MECE classification, cold-start counting, and pattern extraction. Without an Agent, you have empty directories and unused templates — not a functioning knowledge system. See references/platform-guide.md for supported platforms. / 不行，此 Skill 需要 AI Agent 执行协议。

9. Bilingual Terminology / 中英术语对照

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 文件执行全部逻辑。

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)

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/ 复制到对应平台目录：

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 / 四个词上手

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 浏览知识图谱：

1. Open your project folder as an Obsidian vault / 用 Obsidian 打开项目文件夹
2. The .claude/ directory becomes a browsable wiki / .claude/ 目录变成可浏览的 wiki
3. [[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 manu