Knowledge that builds on itself
Unlike search-on-every-question, a hub pre-compiles what you learned into structured notes. The answer is written down once, then reused, instead of being rediscovered from scratch each time.
Your agent forgets everything: every investigation evaporates at session end, and next week it re-derives it all. This fixes that: dense, code-grounded notes an agent reads and writes, so findings compound. The template ships one example sub-hub with sample notes; you clear it and create sub-hubs for the domains you work in.
Works with any coding agent that reads AGENTS.md (Claude Code, Codex, Cursor, Copilot, Gemini CLI, Aider, ...): the contract is the file, not the harness. The three commands below are Claude Code skills (installed by ./install.sh); the same operations are plain CLIs any agent can run (bin/match.mjs, hub-lint.sh). Notes are plain markdown; nothing to host.
Unlike search-on-every-question, a hub pre-compiles what you learned into structured notes. The answer is written down once, then reused, instead of being rediscovered from scratch each time.
One read of the INDEX shows every note in a line each. The agent opens a TL;DR only if it looks relevant, and the full note only when the work needs it. Three tiers, smallest first.
An agent has a finite context window. Dumping every note rots it. A hub hands over a one-line summary plus a short TL;DR, so the agent spends its budget on the work, not on wading through files.
Adoption cost: "Use this template", then ./install.sh. About two minutes to a working setup in Claude Code and Codex.
agent-knowledge-hub/ ├─ AGENTS.md · CONTEXT.md · INDEX.md charter · glossary · sub-hub catalog ├─ install.sh links skills into your agents, records HUB_ROOT ├─ skills/ the three workflows: load-context (read) · store-to-hub (write) · hub-lint (maintain) ├─ scripts/ hub CLI (create/list) · weekly maintenance sweep · citation-drift check ├─ scripts/checks/ deterministic gates: validate-note, check-index, append-log, hub-lint ├─ template/ · docs/ new-hub scaffold · note-format, this guide, ADRs └─ hubs/ YOUR knowledge lives here; everything above is machinery ├─ example/ ships with the template; replace with your own │ ├─ prebuilt-lib-indirection shared-package edits need a rebuild to reach the app │ └─ env-var-not-read tool reads its config file, not your exported env var ├─ your-domain/ e.g. how your product systems behave │ ├─ ...notes one finding per file, one INDEX line each │ └─ works/ active multi-step projects │ └─ some-feature/ numbered files telling the project story └─ your-tooling/ e.g. dev-environment friction + fixes
notes are atomic, cross-project, findable. works/ are goal-bound projects (the live, multi-step research). Both route to whichever sub-hub's charter claims them.
Two kinds of content. A note is atomic and cross-project, findable in the INDEX (evergreen-note style). A work is a goal-bound project: a works/<slug>/ folder of numbered files plus status. Both route by charter, so a tooling project lives in your tooling hub, not your product hub. When an investigation inside a work is reusable beyond it, promote it to a note and link it, so it stays findable; project-specific detail stays in the work. The test: would future-you search for it independent of the project?
There is no fixed list of sub-hubs; you create one per domain you work in. Each sub-hub's AGENTS.md charter declares its scope, and a finding goes to the hub whose charter claims it. One topic never splits across hubs. If no charter fits, that is the signal to create a new sub-hub (./scripts/hub create <name>); /store-to-hub proposes this automatically instead of forcing a bad fit. The two charters below are just this instance's examples of scope declarations:
One real note (shape defined in docs/note-format.md), then how /load-context surfaces it later, INDEX match plus TL;DR, never a full-file dump. Two things never go in a note: PHI and credentials. Cite the pointer (encounter ID, collection path, Keychain item), never the payload; the write gate rejects secret-shaped strings outright.
src/ changes nothing at runtime when consumers import the prebuilt lib/ output. Rebuild (or run the watcher) after any edit. Symptom: source looks right, app unchanged; cause: the build artifact.# resuming the work weeks later /load-context package rebuild # one INDEX read, top matches with their TL;DR, you pick what to open: → prebuilt-lib-indirection.md shared-package edits need a rebuild to reach the app → env-var-not-read.md tool reads its config file, not your exported env var
Phase 04 mostly runs without you. A weekly scheduled job lints every sub-hub (0.3s, deterministic), snapshots any drift into git, checks citation drift (does a note cite code that changed, or was deleted, upstream since the note was written?), and only notifies when something needs attention: a hard failure, or warnings growing. The LLM pass stays on demand, because judgment output belongs in front of a human. A knowledge base that is not health-checked becomes confidently wrong; the loop exists so staleness surfaces before you trust it.
claude-mem is a Claude Code plugin that records your sessions automatically: it hooks into every conversation, compresses what happened (what you investigated, what you changed, what worked) into searchable observations, and injects the relevant ones back into future sessions in that project. You never invoke it; it just runs. That makes it a perfect safety net, and a poor knowledge base: its memory is episodic ("on Tuesday we debugged X and tried Y"), machine-summarized, unverified, and noisy, because it keeps everything, including the dead ends.
The hub is the opposite on every axis, and that contrast is the design:
Why both? Because each lets the other be good at its job. The hub can stay selective (file only findings that clear the bar: 30+ minutes, reusable, non-obvious) precisely because claude-mem already backstops everything below the bar; nothing is lost by not filing it. And claude-mem can stay an unfiltered firehose because the durable conclusions get promoted out of it into the hub. No claude-mem? The split still holds with any passive session-memory, or none; the hub just becomes your only layer and the filing bar drops accordingly.
How a system actually works. The backbone of any note: cite file:line, quote the lines.
Why a change was made. Decisions and the context behind the code, not just the code.
Tribal knowledge: who owns what, history, the reasons that never made it into a doc.
Specs, onboarding, the engineer handbook. The written record to reconcile code against.
Scope, status, and the ticket trail behind a piece of work.
Runtime truth: logs, traces, metrics. What the system does in production, not just in source.
Your own past sessions. "Did I already solve this?" before investigating from scratch.
Starting from empty? Do not backfill everything. Seed the hub with the last three or four investigations that cost you 30+ minutes, then let it grow as you work. The hub earns its keep by accruing, not by being complete on day one.
Matches your topic against every sub-hub INDEX, returns the top notes with their one-line summary and TL;DR as a jump-start, and dives into full notes only on demand. Typo or half-remembered name? When exact matching finds nothing it falls back to fzf (if installed) and presents results as "did you mean". No topic at all? It shows the whole catalog and lets you point.
# get back into a project fast /load-context patient consent # or any topic you have notes on /load-context npm token auth
Classifies the right sub-hub from each charter, dedupes against the INDEX, then shows you a diff and waits. On confirm it writes the note, updates the INDEX, appends a log.md line, and runs the lint. Never writes silently.
# synthesize from the conversation /store-to-hub # or hand it the finding /store-to-hub "admin roles live in firestore accounts collection"
Runs the deterministic gate first (orphans, broken links, missing INDEX or log entries, em dashes, secret-shaped strings, missing TL;DRs, stale small hubs, stalled works), then an LLM pass for what scripts cannot see: contradictions between notes, duplicate topics, stale claims, misrouted or buried findings. Proposes fixes, never applies them.
# one hub /hub-lint example # or every hub, grouped /hub-lint
The skills lean on small deterministic scripts and two reference docs you can read or run by hand.
This hub is a working starter, not just an idea. Clone it, activate the skills, and the notes you see become your examples. Plain markdown plus a few small scripts. Nothing to host.
git clone <repo> ~/workspace/agent-knowledge-hubcd ~/workspace/agent-knowledge-hub && ./install.sh links the skills into Claude Code and Codex (restart them after), makes hooks runnable. Optional: fzf enables typo-tolerant retrieval. Skills only? npx skills add <repo> --all works too./scripts/hub create <your-hub> and use /load-context, /store-to-hub, /hub-lintdocs/adr/.