obsidian-knowledge-brain
AI agent skill that remembers every technical decision & bug fix across sessions — and learns from them. v4.0, MIT. | 跨会话记忆的AI编程助手知识大脑
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/tubo2333--obsidian-knowledge-brain)HTML
<a href="/listings/tubo2333--obsidian-knowledge-brain"><img src="/api/listings/tubo2333--obsidian-knowledge-brain/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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/` 替换为对应目录,然后输入触发词手动执行。
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 189 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # 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 / 标注最低可行标准
- | Annotation | Required Fields | Missing → |
- |-----------|----------------|-----------|
- | `[DECISION:]` | summary + context + project | `# MVA_FAIL:<field>`, 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 <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 / 中英术语对照
- | 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 | 兜底/安全网 |
README.md · README · 204 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # 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)
- ```bash
- 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`: / 可选钩子自动化:
- ```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 浏览知识图谱:
- 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 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 — 随意使用、修改、分发。
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.