| name | knowledge-base |
| version | 0.1.0 |
| audience | agent |
| description | Create and maintain a Markdown knowledge base that any AI agent can read, search, and update. Use when the user wants to start a knowledge base, add or update notes, organize docs/notes for an agent or LLM to consume, build an index of notes, or run a cleanup/maintenance pass on an existing MD knowledge base. Triggers include "knowledge base", "KB", "notes for the agent", "index of notes", "second brain", "docs for AI context", "add a note", "update the KB". |
Knowledge Base (Markdown, agent-readable)
A knowledge base (KB) here is a folder of Markdown files designed so any AI
agent can navigate it without a vector database: the agent reads one index file,
picks the relevant notes by their descriptions, and opens only those. Keep the
whole KB readable and the index lean — the index is what gets loaded into
context, so it must be high-signal.
Apply the rules below when creating a new KB, adding/editing notes, or doing a
maintenance pass. When the user's request is ambiguous (new KB vs. add note vs.
cleanup), ask which one before acting.
Core principles (the "why")
- Index-first navigation. The index is a map, not a container. An agent
reads
INDEX.md, selects notes by their one-line descriptions, then opens
only those files. No note is "in" the KB unless it's registered in the index.
- Atomicity. One topic per note. If a title needs an "and", it's probably
two notes. Atomic notes are easier to find, link, and reuse.
- Stable IDs. Every note has a permanent ID that never changes and is never
reused, so links survive renames and moves.
- Linked with reason. When two notes connect, state why (prerequisite,
supports, contrasts, see-also). Connections carry as much value as the notes.
- Lean instructions. Keep
INDEX.md instructions short and high-signal —
it competes for the agent's context budget. Bodies load on demand.
- Structured for retrieval. Clear H1 title and H2/H3 sections so an agent
can grab the relevant slice of a note, not the whole thing.
Folder structure (nested by topic)
knowledge-base/
INDEX.md # entry point: instructions + full note registry
topics/
<topic>/
_topic.md # topic map: what this topic covers + its notes
<slug>.md # one atomic note
assets/ # images / attachments referenced by notes
- Topic folders are short, lowercase nouns (
auth, billing, deploys).
_topic.md is the topic-level map of content (MOC): a short intro plus links
to every note in that topic. It is a convenience view; INDEX.md remains the
source of truth.
Naming rules
- Lowercase kebab-case, predictable and greppable:
topics/auth/session-tokens.md.
- No spaces, no uppercase, no dates in filenames (dates live in frontmatter).
- The filename slug should match the note's
id slug portion.
Required frontmatter (every note)
---
id: 20260618-session-tokens
title: Session tokens
tags: [auth, security]
created: 2026-06-18
updated: 2026-06-18
related: [20260618-auth-flow]
summary: One scannable sentence describing what this note covers.
---
id: YYYYMMDD-slug. Sortable, readable, stable. Different-titled same-day
notes differ by slug; if two same-day notes would collide on the same slug,
append -2, -3, … (check the INDEX.md registry before assigning). Once
assigned, the id is permanent.summary: this exact sentence is what goes in the index registry — write it to
help an agent decide whether to open the note.updated: bump it whenever the body changes.
Note body shape
# Session tokens
> Summary: One sentence (mirrors frontmatter summary).
## Context
Why this note exists / when it applies.
## Details
The actual content, in short H2/H3 sections.
## Related
- [Auth flow](auth-flow.md) — prerequisite: tokens are issued during the auth flow.
- [Rate limiting](../api/rate-limiting.md) — see-also: tokens carry the rate-limit key.
- Use relative links between notes and annotate the relationship in a phrase.
- Every link target should also appear in the note's
related frontmatter.
INDEX.md (the single source of truth)
INDEX.md has two parts: operating instructions for agents, and the registry.
# Knowledge Base — Index
## How to use this KB (for agents)
1. Read this index first. Pick notes by their descriptions; open only those.
2. To answer a question, prefer opening 1–3 specific notes over scanning everything.
3. Cite the note `id` when you use information from it.
## How to update this KB (for agents)
- New idea → create a new note (atomic). Same idea changed → edit the note in place and bump `updated`.
- Any create / rename / delete MUST update this registry and the topic's `_topic.md` in the same change.
- Use only tags from the controlled vocabulary below; add a new tag here before using it.
## Controlled tags
`auth`, `security`, `billing`, `api`, `ops` <!-- extend deliberately -->
## Registry
### auth
- `20260618-auth-flow` — **Authentication flow** — `topics/auth/auth-flow.md` — How a user session is established end to end.
- `20260618-session-tokens` — **Session tokens** — `topics/auth/session-tokens.md` — Token format, lifetime, and rotation.
### billing
- `20260618-invoicing` — **Invoicing** — `topics/billing/invoicing.md` — How invoices are generated and sent.
Registry line format: `id` — **Title** — `path` — one-line description.
_topic.md (topic map)
# Auth
Notes covering authentication, sessions, and access control.
- [Authentication flow](auth-flow.md) — how a session is established.
- [Session tokens](session-tokens.md) — token format, lifetime, rotation.
Workflows
Create a new KB
create_directory for the folder structure above.write_file INDEX.md with the instructions block, an empty controlled-tag
list, and an empty registry.- Add the first topic folder +
_topic.md, then the first note (each via write_file).
- Register the note in
INDEX.md and link it from _topic.md — edit_block
both so you touch only the changed lines.
Add a note
- Pick or create the topic folder (
list_directory to see what's there).
write_file the note (kebab-case slug) with full frontmatter and the body shape.- Add cross-links (and mirror them in
related).
- Register it in
INDEX.md and link it in _topic.md with edit_block — same change.
Update a note
- Same idea, new information →
edit_block the note in place, bump updated, and
edit_block the registry line if the scope changed.
- Genuinely new idea →
write_file a new atomic note instead of expanding this one.
Maintenance pass (run on demand)
Use start_search (ripgrep) for text scans and get_file_info / list_directory
for existence checks — together they make this tractable at scale:
- Orphans (no inbound links — outbound doesn't matter):
start_search the
KB for the note's id and filename slug, then discount the self-matches that
always exist — the note's own file, INDEX.md, and its _topic.md. Anything
left is a genuine inbound reference; nothing left = orphan, so link it from a
relevant note/MOC or archive it.
- Broken links / drift: don't infer resolution from a text hit — a string
existing doesn't mean the file does. Confirm each registry path and
related:
target exists with get_file_info (or list_directory per topic), and that
every file on disk is registered. Use a text compare only for the
titles/summaries-out-of-sync half.
- Non-atomic notes: notes that grew to cover multiple topics → split them.
- Duplicates: near-identical notes → merge, keep one
id, redirect links.
- Tag sprawl: read the controlled list from
INDEX.md, then start_search
the frontmatter tags: lines and flag any tag not on the list → reconcile.
Pull candidates in bulk with read_multiple_files, apply fixes with edit_block,
and report what changed.
Checklist before finishing any KB edit
