knowledge-base-framework/README.md

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

```sh
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.

```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
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](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"}