Obsidian Knowledge Brain v4.0
An AI coding skill that remembers every technical decision and bug fix across sessions — and evolves your project rules from them.
SKILL.md §0b explicitly declares write scope: project {AGENT_DIR}/, archive/, and a single well-known global dir ~/.obsidian-knowledge-brain/; provides --uninstall marker, atoms..bak backup, lock file, human-confirmed promotion, LLM pattern extraction off by default. Data-flow disclosure is fairly complete; no outbound network calls. Deductions: Pre-Action injection writes into always-loaded Agent instruction files; user-confirmation granularity for install/promotion is not fully shown in SKILL.md; rollback of injected content is described only via marker files, unverified against script sources.
Protocol layering is clear: trigger contracts, MVA validation, MVA_FAIL markers, anti-pollution rules, cold-start protocol show abnormal-path consideration. Deductions: static review executed nothing; the author self-reports Gemini/Codex always-loaded files untested (L2); pointer drift (L8) and metadata loss (L9) have no automated repair; no committed test suite covers key paths, so failure-feedback quality cannot be confirmed.
Target scenario is clear (cross-session knowledge capture for AI coding agents), trigger-word table is concrete, FAQ states non-fit (no Agent = not usable), 20-annotation cold-start threshold, full bilingual docs, no mainland-China-unreachable service dependency. Deductions: boundary depends on always-loaded file support that two platforms admit is unverified; semantic triggering relies on user-remembered phrases with limited false-trigger analysis.
Good progressive disclosure: ≤200-line SKILL.md plus on-demand references; detailed CHANGELOG 2.0→4.0, MIT LICENSE, version badges, 9 declared known limitations, install notes and platform-guide references. Deductions: 20 Python scripts (including v2-legacy setup.py) coexist with unclear deprecation boundaries; maintainer identity unclear (copyright: memory-brain contributors) and no committed update path.
Value proposition (cross-session memory, repeat-pitfall prevention, searchable KB) is specific; cost disclosure is honest (tokens, wrap-up time); marginal value over manual note-taking plausible. Deductions: capture quality and pattern-extraction effectiveness unverifiable statically; ~3-session cold start plus 3,000-8,000 tokens/session recurring cost leaves comparative benefit weakly evidenced and direct usability of outputs unconfirmed.
Auditable primary material exists: CHANGELOG records concrete fixes (eviction sort, lock protection), file manifest matches repo structure, known limitations cross-check behavior. Deductions: no third-party execution evidence, no CI/test corroboration, and mechanisms like hit_rate/chaos score lack external validation — most claims remain author assertions.
- Installation and Pre-Action inject content into always-loaded instruction files and write to ~/.obsidian-knowledge-brain/; back up affected files before installing.
- Always-loaded file support for Gemini CLI / Codex is author-admitted untested (L2); verify the instruction file is actually loaded before relying on these platforms.
- Core value depends on the Agent reliably executing the protocol (wrap-up, MVA checks); skipped steps silently lose knowledge — version-control the .claude/ directory with Git.
- No test suite or CI evidence backs reliability claims; all findings here are static inference, not executed verification.
- Publisher identity is unverified; copyright is attributed to anonymous 'memory-brain contributors' with no clear long-term maintenance commitment.
What does this skill do, and when should you use it?
Knowledge from AI-assisted debugging and technical decisions normally vanishes when a session ends. This skill captures it as [DECISION:] and [ERROR:] annotations, classifies them with MECE rules into a project-local .md knowledge base, and after ~20 accumulated annotations automatically extracts patterns to evolve project rules. v4.0 adds a global atom table so a recurring error seen in 2+ projects can be promoted into shared cross-project knowledge. It is a pure Markdown + Agent-protocol system with no external API calls; Obsidian is an optional graph viewer only. Claude Code gets full automation; Cursor, Gemini CLI, and Codex work via manual trigger words.
At session end it extracts technical decisions and fixed errors into standardized annotations ([DECISION:] requires summary/context/project; [ERROR:] requires type/resolution/project), MECE-classifies them into memory/; on first use it runs a bootstrap that scores project chaos and builds a rules/, projects/, memory/ skeleton; at each session start it injects a project briefing with past pitfalls; a periodic health check runs a 7-dimension scan (contradictions, orphans, GC, pattern extraction); when the same root cause appears in ≥2 projects it can be promoted — with human confirmation — to ~/.obsidian-knowledge-brain/atoms. (cap 20 atoms, auto-demote after 365 days without trigger). All classification is deterministic; no external APIs are called.
What are this skill's strengths and limitations?
- Zero monetary cost, zero external APIs: pure Markdown templates plus deterministic rules, no servers or subscriptions
- Cross-platform across Claude Code, Cursor, Gemini CLI, and Codex, with a one-command path-rewriting installer
- Serious anti-pollution design: only final adopted solutions and fixed errors are stored; duplicate root causes increment a counter instead of creating new files
- Explicit sandbox boundaries: project writes limited to the agent directory and archive/; the only global path is ~/.obsidian-knowledge-brain/
- Thorough documentation including a known-limitations list (L1-L9), troubleshooting guide, and 5-minute quickstart
- Requires an AI Agent with file read/write — plain-terminal or agent-free use is explicitly unsupported
- Non-Claude-Code platforms are degraded: T1/T2/T3 all need manual trigger words; hooks and auto wrap-up are unavailable
- Always-loaded files for Gemini CLI (.gemini/extensions.) and Codex (.codex/codex.yaml) are listed but unverified/tested
- No test suite is mentioned in the source; the README's v2.0→v3.0→v4.0 evolution tables contain minor inconsistencies (e.g., script counts) users must reconcile
- Cross-machine sync of atoms. is manual; pointer drift (stale rule line numbers) is flagged but never auto-repaired
- Ongoing cost of roughly 3,000-8,000 tokens and ~2 minutes of wrap-up per session
How do you install this skill?
Claude Code: git clone https://github.com/Tubo2333/obsidian-knowledge-brain.git .claude/skills/obsidian-knowledge-brain/ — auto-loads on next session start. Optional hook automation in settings.: SessionStart → session_start.py, Stop → session_close.py --prompt, weekly cron → maintainer.py --health-check. Cursor: copy to .cursor/skills/obsidian-knowledge-brain/; Gemini CLI: .gemini/extensions/; Codex: .codex/skills/; or run python scripts/install.py --platform cursor (also supports gemini/codex) to rewrite paths. Uninstall with the --uninstall flag; the global atoms. is preserved for reinstall.
How do you use this skill?
First time, type 'diagnose' (read-only scan with chaos score and plan) or 'bootstrap' (full skeleton build, gated behind confirmation). Then just work normally: after fixing any error the Agent appends a one-line [ERROR:] stub to the inbox immediately; at session end type 'wrap up' (or let CC hooks fire) to extract decisions, update rules, and emit [SESSION_SUMMARY]. Other triggers: 'health check', 'rule audit', 'memory cleanup', 'rebuild index', 'skill status'. Pattern extraction activates after ~20 annotations across ~3 sessions.
How does this skill compare with similar options?
The README explicitly compares the project's own v2.0 (Obsidian vault + Python scripts + single platform), v3.0 (skill-only, project-local), and v4.0 (global atom table with ≤20 cross-project atoms): v2.0 was heavy, v3.0 trapped knowledge per-project, v4.0 compromises with a capped global table. Versus Claude Code's built-in CLAUDE.md project memory, this adds structured classification, pattern extraction, and cross-project reuse — at notably higher complexity.