mganter/knowledge-base-framework
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: extract kb_framework package, build graph in memory

Browse Source 
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>
This commit is contained in:
TotenKnopf
2026-10-06 20:40:13 +02:00
co-authored by Claude Fable 5.1
parent 4fec637599
commit 96780317a7
37 changed files with 1858 additions and 899 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENT_QUERY_GUIDE.md
+12 -7
View File
@@ -4,14 +4,17 @@ title: Agent Query Guide
type: meta
status: active
tags: [agents, jq, graph]
last_reviewed: 2026-06-16
last_reviewed: 2026-10-06
---
# Agent Query Guide
`index/graph.json` is the selected vault's navigation index. MCP is the canonical
cross-repository interface: `graph_summary`, `graph_search_nodes`,
`graph_neighbors`, and `read_note`; use `refresh_graph(validate=true)` to update it.
The graph is the selected vault's navigation index, built in memory from the
Markdown by `kb_framework.graph.build_graph` — no file is read or committed.
MCP is the canonical cross-repository interface: `graph_summary`,
`graph_search_nodes`, `graph_neighbors`, and `read_note`; the server rebuilds
the graph after every write, and `refresh_graph(validate=true)` rebuilds it on
demand and reports validation problems.
MCP-only agents use the tools above; shell examples below are for operators,
not agent fallback. For those queries, explicitly set `KNOWLEDGE_BASE_ROOT` and change into
@@ -72,7 +75,9 @@ optional JSON brace suffix carrying the relationship and annotation:
fails on any that remain. Locate and convert them with
`python3 "$KNOWLEDGE_BASE_FRAMEWORK_ROOT/scripts/list-wiki-links.py" --vault-root "$KNOWLEDGE_BASE_ROOT"`.
Examples with `jq`:
Examples with `jq` (operators only; first dump the graph with
`python3 "$KNOWLEDGE_BASE_FRAMEWORK_ROOT/scripts/generate-graph.py" --vault-root "$KNOWLEDGE_BASE_ROOT" --write`,
which writes `index/graph.json` — keep `index/` out of git):
```bash
# list repos
@@ -118,8 +123,8 @@ Validation:
# outside their vocabularies, OR any remaining legacy [[wiki links]]
python3 "$KNOWLEDGE_BASE_FRAMEWORK_ROOT/scripts/generate-graph.py" --vault-root "$KNOWLEDGE_BASE_ROOT" --validate
# regenerate graph and validate
python3 "$KNOWLEDGE_BASE_FRAMEWORK_ROOT/scripts/generate-graph.py" --vault-root "$KNOWLEDGE_BASE_ROOT" && python3 "$KNOWLEDGE_BASE_FRAMEWORK_ROOT/scripts/generate-graph.py" --vault-root "$KNOWLEDGE_BASE_ROOT" --validate
# write a graph dump for jq AND validate in one run
python3 "$KNOWLEDGE_BASE_FRAMEWORK_ROOT/scripts/generate-graph.py" --vault-root "$KNOWLEDGE_BASE_ROOT" --write --validate
# list any remaining legacy [[wiki links]] (rejected by --validate) to convert
python3 "$KNOWLEDGE_BASE_FRAMEWORK_ROOT/scripts/list-wiki-links.py" --vault-root "$KNOWLEDGE_BASE_ROOT"