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

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"}

2.6 KiB Raw Blame History