obsidian-knowledge-brain

Files (46)

• bug_report.md · .github/ISSUE_TEMPLATE/
• feature_request.md · .github/ISSUE_TEMPLATE/
• PULL_REQUEST_TEMPLATE.md · .github/
• .gitignore
• CHANGELOG.md
• LICENSE
• README.md
• SKILL.md
• description.md
• domain-registry.md · references/
• error-taxonomy.md · references/
• phase-a-bootstrap.md · references/
• platform-guide.md · references/
• quickstart.md · references/
• root-cause-kb.md · references/
• t1-session-start.md · references/
• t2-session-end.md · references/
• t3-periodic-check.md · references/
• troubleshooting.md · references/
• __init__.py · scripts/
• analyzer.py · scripts/
• backup.py · scripts/
• benchmark.py · scripts/
• compiler.py · scripts/
• config.example.yaml · scripts/
• config.py · scripts/
• global_atoms.py · scripts/
• install.py · scripts/
• keyword_index.py · scripts/
• link_validator.py · scripts/
• maintainer.py · scripts/
• pre_action.py · scripts/
• reformat_tables.py · scripts/
• reporter.py · scripts/
• requirements.txt · scripts/
• runner.py · scripts/
• score_sessions.py · scripts/
• session_close.py · scripts/
• session_harvester.py · scripts/
• session_start.py · scripts/
• setup.py · scripts/
• validate_frontmatter.py · scripts/
• decision.template.md · templates/
• pitfall.template.md · templates/
• project.template.md · templates/
• rule.template.md · templates/

SKILL.md (first lines)

# 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 / 平台矩阵

| | 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 <X>` |

○ = 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)

| 中文 / 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 → [SESSION_SUMMARY] |
| "健康检查" / "health check" | T3 full 7-dim scan → HEALTH_REPORT.md |
| "规则审计" / "rule audit" | Rules-only: contradiction, staleness, ceiling, GC |
| "记忆整理" / "memory cleanup" | MECE re-classify inbox → memory/ + dedup merge |
| "重建索引" / "rebuild index" | Rebuild _keyword_index.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 / 标注最低可行标准

From Tubo2333/obsidian-knowledge-brain, MIT.