knowledge-base-framework/README.md

id, title, type, status, tags, last_reviewed

id	title	type	status	tags	last_reviewed
knowledge-base/home	Knowledge Base	hub	active	knowledge-base agents docs para	2026-09-11

Knowledge Base

A Markdown knowledge graph for engineering agents, organized with the PARA method — notes live by actionability, not by topic.

This repository is the empty framework: tooling, agents, skills and the PARA skeleton, with no notes in it. Clone it, run the bootstrap below, and start writing notes.

Layout

01_projects/    active efforts with a goal and an end (features in flight)
02_areas/       ongoing responsibilities & standards (policies, value streams, decisions)
03_resources/   reference material (repo info, ingested externals)
04_archives/    inactive items moved out of the three live categories
kb_framework/   importable core: in-memory graph build, queries, note access policy
scripts/        graph generator, link inventory, MCP server, git hook
agents/         subagent definitions, symlinked into .claude/agents/
skills/         skill definitions, symlinked into .claude/skills/
tests/          unit tests for the tooling

The PARA buckets start empty — add notes per the layout above, each in its own folder with an index.md.

Bootstrap

make install-hooks           # pre-commit hook: validate the graph (nothing written)
make install-global-claude   # link skills & agents into ~/.claude so any repo can use them
make install-mcp-claude      # register scripts/mcp-server.py as the knowledge-database MCP server
make graph                   # validate the graph (built in memory); `make generate-graph` writes index/graph.json
make test                    # run the tooling tests

External data vault

Keep this repository as the control plane (tools, skills, agents, hooks, tests, operational documentation), and store notes in a separate data repository. The empty PARA skeleton also supports self-contained use.

All Python commands select data with --vault-root, then the KNOWLEDGE_BASE_ROOT environment variable, then this framework's root. An explicit root must be an existing directory; Git operations require it to be the Git repository root. The working directory does not select the vault.

python3 /path/to/framework/scripts/mcp-server.py --vault-root /path/to/vault
make -C /path/to/framework graph VAULT_ROOT=/path/to/vault
make -C /path/to/framework install-hooks VAULT_ROOT=/path/to/vault
make -C /path/to/framework install-mcp-claude VAULT_ROOT=/path/to/vault

VAULT_ROOT defaults to KNOWLEDGE_BASE_ROOT, then the framework directory. The hook installer honors Git's hooks directory (including worktrees and core.hooksPath), preserves unmanaged hooks, and writes a wrapper pointing at framework tooling. Reinstall after moving the framework or vault. The hook validates the selected vault's graph in memory; it writes nothing and never requires a staged index/graph.json.

Configure each stdio MCP client with command python3 and arguments ["/path/to/framework/scripts/mcp-server.py", "--vault-root", "/path/to/vault"]. MCP reads, writes and Git operations use that vault. The graph is built in memory on first use and rebuilt after every write; refresh_graph rebuilds it on demand and, with validate=true, applies the commit gate. No graph file is read or written. A README resource is advertised only if present.

Global skill and agent symlinks must point into this framework. MCP is their only interface for vault access; unavailable operations are reported without shell fallback. The CLI examples here are for operators. No personal taxonomy is assumed. Agents call read_instructions to load framework AGENTS.md and AGENT_QUERY_GUIDE.md even before a data graph exists. This read-only tool returns those two framework documents; read_note remains vault-scoped.

For migration, test the external root first, back up MCP configurations and symlink targets, cut clients and hooks over, then smoke-test initialize, tools/list, graph_summary, search, read and refresh. Only remove old tool copies after this passes. On failure restore the configs and symlinks and retain the old copies. Restart existing clients to load the new server command.

A minimal data repository contains 01_projects/ through 04_archives/ and repository hygiene; index/ is not committed. Before removing a root hub, replace its inbound links with links between PARA hubs and validate the graph. Preserve untracked files separately from the tracked-file cleanup.

Generation

• The graph is derived in memory by kb_framework.graph.build_graph; run make graph to validate it
• make generate-graph writes index/graph.json for operators who want a file; keep index/ out of git

Rules

• Markdown is the source of truth
• The graph is derived; never hand-edit or commit a graph dump
• Keep notes linked using typed markdown links: [text](note-id){"type":"…"} (legacy [[wiki links]] are rejected by make validate-graph)
• Organize by PARA actionability; move notes between buckets as that changes
• Fix broken links — find them with make graph or make validate-graph

Hubs

• Projects Hub{"type":"related","link-info":"Lists the active projects"}
• Areas Hub{"type":"related","link-info":"Lists the ongoing areas of responsibility"}
• Resources Hub{"type":"related","link-info":"Lists the cataloged reference notes"}
• Archives{"type":"related","link-info":"Lists items moved out of the live buckets"}
• Agent Query Guide{"type":"see-also","link-info":"Graph schema and jq queries for agents"}