Obsidian Knowledge Brain

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= | resolution= | project: ] 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=].

1. [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: | context: | project: | scope: project|cross-project] and [ERROR: type= | resolution= | project: ]. Missing required fields → mark # MVA_FAIL: 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 /{AGENT_DIR}/ and /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=]. Skip Post error recording → [ERROR: type=missed-record | error_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 rootcauseid → 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 / 平台矩阵

| | Claude Code | Cursor / Gemini CLI / Codex | |---|------------|---------------------------| | Pre-action | ✅ Auto | ✅ Auto (if always-loaded file exists) | | T1/T2/T3 | ✅ Hook/Cron auto | ○ Manual: user trigger words | | Promotion | ✅ T2 auto | ○ Manual: Agent prompts during T2 | | install.py | ✅ python scripts/install.py | ✅ --platform |

○ = 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: ISRULE/ISPROJECT/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)

| 中文 / English | Agent Action | |---|---| | "诊断" / "diagnose" | Phase A Pass 1 (READ-ONLY): scan project → chaos score + plan. No files modified. | | "整理项目" / "bootstrap" | Phase A full: diagnose → plan → [confirm] → build → migrate → validate | | "继续播种" / "resume bootstrap" | Resume interrupted Phase A from last checkpoint | | "收尾" / "wrap up" | T2 F2: Phase 1 quick close (3-step) → write memory → [SESSIONSUMMARY] | | "健康检查" / "health check" | T3 full 7-dim scan → HEALTHREPORT.md | | "规则审计" / "rule audit" | Rules-only: contradiction, staleness, ceiling, GC | | "记忆整理" / "memory cleanup" | MECE re-classify inbox → memory/ + dedup merge | | "重建索引" / "rebuild index" | Rebuild keywordindex.json + CLAUDE.md index tables | | "Skill 状态" / "skill status" | Output: Phase A/B state, inbox backlog, last health check, cold-start progress |

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

| Annotation | Required Fields | Missing → | |-----------|----------------|-----------| | [DECISION:] | summary + context + project | # MVA_FAIL:, stay in inbox | | [ERROR:] | type (from error-taxonomy) + resolution + project | same | | [SESSION_SUMMARY] | decisions + errors + rules_triggered | same |

Quality target: ≥90% field completeness. 3 consecutive sessions 4 files → Agent uses these to create rules/projects/pitfalls/decisions 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 `/.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 / 中英术语对照

| English | 中文 | English | 中文 |
|---------|------|---------|------|
| Framework Skeleton | 框架骨架 | Memory Engine | 记忆引擎 |
| Trigger Contract | 触发契约 | Annotation | 标注 |
| Chaos Score | 混沌度 | Cold Start | 冷启动 |
| MECE Classification | 互斥穷尽分类 | Pattern Extraction | 模式提取 |
| Root Cause KB | 根因知识库 | Error Taxonomy | 错误分类法 |
| Pitfall | 陷阱 | Decision | 决策 |
| Health Check | 健康检查 | Bootstrap | 播种/减负 |
| Deferred Audit | 延迟审计 | Safety Net | 兜底/安全网 |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Tubo2333](https://github.com/Tubo2333)
- **Source:** [Tubo2333/obsidian-knowledge-brain](https://github.com/Tubo2333/obsidian-knowledge-brain)
- **License:** MIT

Install and usage instructions live in the source repository linked above.