knowledge-gardener
A Claude Code plugin for tending a long-term knowledge base from inside your coding sessions.
What It Does
Decides when to capture, update, link, or prune durable knowledge in your external vault (Obsidian, a plain markdown folder, anything with a README). Defers how — note format, filename rules, link syntax, frontmatter, folder layout — to the vault's own README. This separation is the whole point.
The vault is the source of truth for how.
This plugin is the source of truth for when.
Why This Exists
Most "Obsidian-for-Claude" plugins hardcode a note format (PARA, Zettelkasten with Luhmann IDs, daily-note schemas, etc.). That makes them useful only if your vault matches the plugin's assumptions. The moment your vault has its own README spelling out conventions, those plugins fight you.
knowledge-gardener flips it: the plugin reads your vault's README before each operation and applies whatever conventions are documented there. Bring your own format.
Installation
Inside Claude Code:
/plugin marketplace add Kohei-Wada/knowledge-gardener
/plugin install knowledge-gardener@knowledge-gardener
Set the vault path in your shell:
export KG_VAULT=~/path/to/your/vault
export KG_BLOG_REPO=~/path/to/your/blog/repo # only needed for garden-harvest
Restart your Claude Code session.
Vault Prerequisites
Your vault MUST have a README.md that documents at least:
- Folder layout — where do different kinds of notes go?
- Filename rules — kebab-case? Luhmann ID? date prefix?
- Link syntax —
[[wikilink]], [md](rel-path.md), or both?
- Frontmatter schema — required fields, if any
- Tag namespace — any constraints
The README can live at either:
$KG_VAULT/README.md — vault root (most specific, wins on conflict), or$KG_VAULT/../README.md — parent directory (common when the vault is a subdirectory of a git repo, e.g. Obsidian/vault/)
garden-plant reads both and merges; folder-scoped READMEs (e.g. $KG_VAULT/06_People/README.md) are also consulted when relevant.
If no README is found in either location, garden-plant will refuse to write and tell you what's missing. That's intentional: silent defaults are how vaults end up inconsistent.
How It Works
- You converse with Claude as normal.
- A durable insight surfaces — a decision, a lesson, a workflow, a reference worth remembering.
- Claude proposes a note — path, content, and rationale — formatted per your vault's README.
- You approve. Claude writes the file. (Or skip the approval step by saying "save this to my vault".)
- You commit on your own cadence. The plugin never auto-commits or pushes.
What's Inside
Skills
| Skill | What it does |
|---|
using-knowledge-gardener | Entry point — routes requests, declares the format contract |
garden-plant | (implemented) Capture a new durable insight as a vault note |
garden-survey | (implemented) Read-only search/listing primitive (text, tag, frontmatter, folder). Used directly and by other skills |
garden-water | (implemented) Update an existing note — append content, add a link, fix a tag or frontmatter field. Minimal-diff edits |
garden-recap | (implemented) Wrap up a session by writing what was worked on to today's daily note, so the next session can pick up context |
garden-connect | (implemented) Link an existing MOC and an existing child note — atomic graph-edge insertion, bi-directional by default |
garden-prune | (implemented) Remove a named note — archive by default (git mv into the vault's archive folder), hard-delete only on explicit request. Surfaces inbound-link warnings; cleanup goes through garden-water |
garden-harvest | (implemented) Turn mature vault knowledge into a published blog post — gather permanent notes, shape in dialogue (no stored draft), mask PII, emit into the blog repo (KG_BLOG_REPO) per that repo's conventions; commits, never pushes |
Session Capture (Phase 1)
Starting in v0.8.0, knowledge-gardener ships a PostToolUse hook that records a one-line evidence entry per material tool call to:
$XDG_STATE_HOME/knowledge-gardener/sessions/<YYYY-MM-DD>-<sid8>.log
Default location: ~/.local/state/knowledge-gardener/sessions/. Modes 0700 (dir) / 0600 (file).
What gets recorded:
- File-mutating tools (
Edit, Write, NotebookEdit)
- Non-trivial
Bash (after stripping cd <dir> && prefixes; trivial commands like ls, pwd, cat, grep, rg, wc, sort, date, etc. are filtered)
Agent dispatches (subagent type + short description)WebFetch / WebSearch (URL or query)- MCP tool calls (
mcp__<server>__<name> + one identifying argument)
What is skipped:
- Read-only tools (
Read, ToolSearch, AskUserQuestion, …)
- Internal task plumbing (
TodoWrite, TaskCreate, TaskUpdate, …)
- Trivial shell commands
