agent-knowledge-hub
personal knowledge monorepo

agent-knowledge-hub

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.

01

Why a hub at all

Three problems it solves that a fresh chat does not.
compounding

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.

progressive disclosure

Read the index, not the library

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.

context budget

Lean by construction

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.

R

Receipts, not claims

What this machinery has actually caught, from the original instance it was built in.
a real contradiction, caught
two notes disagreed about the same fix (one said "run the login command", the other proved that harmful). The lint pass surfaced it before it cost anything; the notes were merged into one canonical answer.
3 dead citations, found automatically
the weekly citation-drift check compared notes against upstream code and flagged three notes citing files that had moved or been deleted. Confidently-stale knowledge is the worst kind; now it surfaces on a schedule.
retrieval is tested, 100% eval
a regression-gated eval runs the matcher against the real hubs (exact + fuzzy cases). Selection quality is measured, not assumed; the eval once caught an INDEX entry polluting results.
adopted by a stranger, from docs alone
a zero-context agent was pointed at this repo's README and completed the full loop (install, new hub, note, retrieve, lint) unaided. Its five friction findings were fixed; that gate is now in CONTRIBUTING.

Adoption cost: "Use this template", then ./install.sh. About two minutes to a working setup in Claude Code and Codex.

02

How it is built

One umbrella, full sub-hubs, and a strict read-ladder.
repository shape
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.

the read-ladder
1 INDEX one-liner One read. Every note described in a line. Triage here. 1 read = all N notes 2 ## TL;DR First lines of a note. Read only if the one-liner looks relevant. 3 Full note body Opened only when the work actually needs the detail.

Notes vs works

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?

Routing: charters decide, and the hub set grows

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:

your-tooling (example)

charter scope: local env, tooling, auth, IDE, CLI friction
  • the "this wasted my time, automate it" pile
  • example note: env-var-not-read

your-domain (example)

charter scope: how your product systems behave, code-grounded
  • your services, your repos
  • example note: prebuilt-lib-indirection

What a note looks like

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.

hubs/example/prebuilt-lib-indirection.md

# Shared package edits do not reach the running app

## TL;DR Editing a shared package's 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.
Then: body sections citing code with line ranges, a verified-vs-inferred section, sources, and related notes. The shape is the same for every note.
# 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
03

A working session

Four phases. Prime, gather, capture, maintain.
the loop
01 Prime /load-context <topic> pull existing notes, start warm 02 Gather code / slack / datadog do the work, cite sources as you go 03 Capture /store-to-hub file the finding if it clears the bar 04 Maintain /hub-lint catch rot before you trust a note

It maintains itself

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.

Two memory layers, not one

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:

claude-mem · the safety net

"what did we do, and when?"
  • passive: captures every session automatically
  • episodic: a timeline of what happened
  • machine-summarized, unverified, keeps the dead ends
  • queried when you wonder "did we already solve this?"

the hub · the compounding asset

"how does X actually work?"
  • deliberate: written only on /store-to-hub, after your confirm
  • semantic: distilled conclusions, not session history
  • human-verified, code-cited, dead ends excluded
  • read at the start of work, via /load-context

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.

04

Where the knowledge comes from

A note is distilled from what you read while working. These are the wells.
code · LSP / ripgrep

How a system actually works. The backbone of any note: cite file:line, quote the lines.

github · PRs / commits

Why a change was made. Decisions and the context behind the code, not just the code.

slack

Tribal knowledge: who owns what, history, the reasons that never made it into a doc.

notion

Specs, onboarding, the engineer handbook. The written record to reconcile code against.

linear

Scope, status, and the ticket trail behind a piece of work.

datadog

Runtime truth: logs, traces, metrics. What the system does in production, not just in source.

claude-mem

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.

05

Jumpstart

Three commands cover the whole loop: read, write, maintain.
/load-context resuming work, or spinning up on a topic after a break

what it does

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.

try it

# get back into a project fast
/load-context patient consent

# or any topic you have notes on
/load-context npm token auth
/store-to-hub after an investigation produces a durable learning

what it does

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.

try it

# synthesize from the conversation
/store-to-hub

# or hand it the finding
/store-to-hub "admin roles
live in firestore accounts collection"
/hub-lint before trusting hub notes for important work

what it does

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.

try it

# one hub
/hub-lint example

# or every hub, grouped
/hub-lint

Underneath: the CLI, the gate, the conventions

The skills lean on small deterministic scripts and two reference docs you can read or run by hand.

./scripts/hub create <name>
scaffold a new sub-hub from the template
./scripts/hub list
list sub-hubs with note counts
scripts/checks/hub-lint.sh <hub>
the deterministic health gate, exits nonzero on a BLOCK
scripts/checks/append-log.sh <hub> <op> <note> <why>
add one append-only line to the hub log
docs/note-format.md
the canonical note shape store-to-hub writes and hub-lint checks
CONTEXT.md
glossary: sub-hub vs note vs work, the routing boundary

Clone it and run your own

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.

  1. Clone into place: git clone <repo> ~/workspace/agent-knowledge-hub
  2. Activate: cd ~/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
  3. Start fresh: read the sample notes for the style, clear them, then ./scripts/hub create <your-hub> and use /load-context, /store-to-hub, /hub-lint
06

Grounding

The sources this design is built on, and what each one contributed. Decisions recorded in docs/adr/.
"smallest set of high-signal tokens"; just-in-time retrieval via lightweight identifiers = the INDEX; structured note-taking outside the context window
the pattern itself: an LLM-maintained markdown knowledge base with an index, a log, and a lint loop
memory as a versioned filesystem; filenames as navigational signal; the case for git (deferred, ADR 0001)
the three-tier read-ladder: lightweight index, details on demand, source last; context rot is the failure mode
freshness beats search: "better retrieval of stale data returns wrong answers faster"; why hub-lint exists
projects vs resources = works vs notes; reusable material gets promoted out of finished projects
notes are atomic, concept-oriented, cross-project; drain reusable findings out of project folders
findability: a work links to notes instead of burying them; one home, many links
the skill design grammar: tiny frontmatter, embedded templates, linked FORMAT docs, propose-then-act
memory, compaction, and tool-result clearing mechanics behind the session loop