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
index/          generated graph (index/graph.json)
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: regenerate + validate the graph
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                   # generate index/graph.json and validate it
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 regenerates and validates the selected vault, then rejects unstaged graph changes.

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; refresh_graph invokes the framework generator by absolute path and writes the selected graph even when validation is requested. 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/, index/graph.json and repository hygiene. 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

Run make graph
Output is written to index/graph.json

Rules

Markdown is the source of truth
index/graph.json is derived and generated
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"}

5.2 KiB Raw Blame History