112 lines
5.2 KiB
Markdown
112 lines
5.2 KiB
Markdown
---
|
|
id: knowledge-base/home
|
|
title: Knowledge Base
|
|
type: hub
|
|
status: active
|
|
tags: [knowledge-base, agents, docs, para]
|
|
last_reviewed: 2026-09-11
|
|
---
|
|
|
|
# Knowledge Base
|
|
|
|
A Markdown knowledge graph for engineering agents, organized with the
|
|
[PARA method](https://fortelabs.com/blog/para/) — 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
|
|
|
|
```sh
|
|
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.
|
|
|
|
```sh
|
|
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](project/index){"type":"related","link-info":"Lists the active projects"}
|
|
- [Areas Hub](area/index){"type":"related","link-info":"Lists the ongoing areas of responsibility"}
|
|
- [Resources Hub](resource/index){"type":"related","link-info":"Lists the cataloged reference notes"}
|
|
- [Archives](archive/index){"type":"related","link-info":"Lists items moved out of the live buckets"}
|
|
- [Agent Query Guide](meta/agent-query-guide){"type":"see-also","link-info":"Graph schema and jq queries for agents"}
|