Files

T

TotenKnopfandClaude Fable 5.1 96780317a7 refactor: extract kb_framework package, build graph in memory

Scripts become thin CLIs over kb_framework (graph, query, query_tools,
vault, instructions) so the hosted read-only connector shares one
implementation with the stdio server. The MCP server builds the graph
from Markdown on demand and invalidates it on writes; refresh_graph
rebuilds in memory and reports validation problems. Pre-commit hook
validates only; index/graph.json is no longer read, written or staged
(generate-graph.py --write remains for operators). Golden fixtures pin
graph and tool payloads to the previous output. Agent and skill docs
updated to match.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

2026-10-06 20:40:13 +02:00

4.6 KiB

Raw Blame History

name, description

name	description
knowledge-base-read	Read and query the knowledge-base vault — a personal docs-as-code knowledge database (PARA-organized). Use when the user asks what is known about a repo, policy, decision (ADR), area, or project; wants context before working in a repo; or asks to find/navigate notes by tag, type, repo, or link. Resolves the question against the Markdown notes and the graph the MCP server builds from them in memory.

name

description

knowledge-base-read

Read and query the knowledge-base vault — a personal docs-as-code knowledge database (PARA-organized). Use when the user asks what is known about a repo, policy, decision (ADR), area, or project; wants context before working in a repo; or asks to find/navigate notes by tag, type, repo, or link. Resolves the question against the Markdown notes and the graph the MCP server builds from them in memory.

Read the Knowledge Base

This vault is a personal docs-as-code knowledge database, organized with the PARA method. Markdown is the source of truth; the graph is a navigation index the MCP server builds from it in memory (nothing on disk). Use this skill to answer questions FROM the vault and to surface the exact notes that back the answer.

Call read_instructions on knowledge-database to read the framework's AGENTS.md and AGENT_QUERY_GUIDE.md before querying the vault. These documents are not data-vault nodes. If unavailable, report the missing instructions. This skill is read-only — do not modify notes here.

Vault access

The knowledge-database MCP server is the only interface for vault access. Use graph_summary to orient, graph_search_nodes to find notes, graph_neighbors to traverse links, and read_note to read the source. Use refresh_graph when the graph looks stale. Skills and operational documentation belong to the framework; never infer the data vault from this skill's file location.

Layout (PARA)

01_projects/                 active efforts with a goal and an end
02_areas/                    ongoing standards: policies, value-stream areas, decisions
02_areas/decisions/          global ADRs
03_resources/meta/           taxonomy + note templates
03_resources/repos/<repo>/   per-repo info.md (+ decisions/)
03_resources/repos/repo-landscape.md   index of documented repos
04_archives/                 inactive items

Every note carries taxonomy frontmatter: id, title, type (hub|project|area|guideline|policy|feature|roadmap|decision|note|meta|reference, enforced by refresh_graph(validate=true)), status (active|draft|deprecated), tags, last_reviewed, optional repo. Notes are linked with typed markdown links — [text](note-id){"type":"…"} — that resolve by id. Legacy [[wiki links]] are rejected by refresh_graph(validate=true).

1. Orient

Start broad, then narrow. Begin with graph_summary, then find hubs using graph_search_nodes(type="hub") and read relevant ones with read_note. Discover repo scopes and tags from the graph rather than assuming a particular folder layout. An external data vault need not contain a root README or framework operational documents.

2. Query the graph

Use the MCP tools directly:

Need	Tool
Repo scopes, tag spellings, most-linked notes	`graph_summary`
Notes in a repo	`graph_search_nodes(repo="<repo>")`
Notes of a type	`graph_search_nodes(type="policy")`
Notes with a tag	`graph_search_nodes(tag="<tag>")`
Search ids, titles, paths and tags	`graph_search_nodes(query="<term>")`
Incoming/outgoing links, relationship types and annotations	`graph_neighbors(id="<note-id>")`

query does not search note bodies. Read candidate notes with read_note and follow their neighbors when metadata search is insufficient. Report any search coverage limits; do not use filesystem or shell searches.

3. Read the source notes

The graph gives ids and paths; the ANSWER lives in the Markdown. Read matched notes with read_note(id="<note-id>") or read_note(path="<vault-relative-path>"). Follow the typed markdown links [text](id){"type":"…"}, resolving each to its node path to pull in related policies, decisions, and repo info. Use each edge's type and annotation to judge which links are worth following; links are the intended navigation, so traverse them rather than guessing.

If the graph looks stale or a path is missing, use refresh_graph. This rebuilds the in-memory graph; it does not touch Markdown. Nothing to commit.

4. Answer with citations

Answer the question directly from what the notes say.
Cite the backing notes by vault-relative path (e.g. 03_resources/<resource>/index.md) and/or id so the user can verify.
Distinguish vault facts from inference. If the vault does not cover it, say so plainly — do not invent. Note status: draft/deprecated when relevant.
For "what links to / relates to X" questions, report the inbound/outbound edges you found, including each edge's relationship type and annotation.

4.6 KiB Raw Blame History