A knowledge base for your coding agents

Coding agents lose useful context when a session ends. The next agent can search the code again, but it cannot recover a source that was never saved, a decision that stayed in chat, or the relationship between two notes that nobody recorded. Repeating that work costs time and produces inconsistent answers.

Search alone cannot preserve agent memory. The system also needs a write path into inspectable files under version control: evidence can be captured, current understanding can be revised, plans can accumulate outcomes, and mandatory edit rules can move onto the instruction path. Search indexes, graph views, and embeddings used for meaning-based similarity should remain derived and replaceable.

hraness/kb implements that split as repository-adjacent Markdown and Git. Exact lookup, metadata filters, local search, explicit links, and Git provenance help an agent find and inspect the files without making application code depend on the knowledge system.

The pattern converged across agent tools

Devin's 2024 release history records Knowledge that could be recalled across future sessions and Repo Knowledge produced by scanning repositories. Its 2025 release history records DeepWiki in April, codebase intelligence inside Devin in May, and a DeepWiki Model Context Protocol server later that month.

In April 2026, Andrej Karpathy published an LLM Wiki proposal with immutable raw sources, an agent-maintained interlinked Markdown wiki, and an instruction schema. Its operations are ingest, query, and lint, with QMD as an optional search layer when a simple index stops being enough. These systems converged on durable agent-readable knowledge. The sequence does not establish direct lineage between them or hraness/kb.

Separate rules from explanations

A repository needs two kinds of memory. Rules that must govern an edit belong in a scoped AGENTS.md file on the path to the code. Rationale, history, examples, evidence, plans, and neighboring decisions belong in a knowledge base that an agent pulls only when the task needs them. This keeps mandatory instructions short without throwing away the context behind them.

A root guide carries repository-wide policy, and nested guides add constraints owned by a package or product. A nearby knowledge note can explain why a parser rejects a tempting shortcut, preserve the source behind the decision, and link the plan that introduced it. If the note and the applicable guide disagree, the guide controls the edit and the note needs repair. Agent docs hygiene covers that instruction path in more detail.

The result has two concrete parts: scoped instruction files govern edits, while an ordinary Markdown vault stores supporting context. Application code imports neither the vault nor its search indexes:

repository/
├── AGENTS.md                         # inherited root rules
├── packages/parser/
│   ├── AGENTS.md                     # scoped rules and checks
│   └── src/
└── kb/
    ├── articles/<slug>/              # captured evidence and assets
    ├── notes/                         # maintained explanations
    ├── plans/                         # decisions and outcomes
    └── index.md                       # regenerated catalog

Keep the implementation small and the files authoritative

hraness/kb packages the pattern as a small file contract. A useful vault can begin with Markdown, Git, index.md, and standard file search. Source capture, metadata queries, QMD, typed relationships, graph traversal, and TypeScript sessions are layers to add when the simpler setup stops answering the repository's questions. Application code need not import KB, and no hosted service or graph database owns its records.

Captured sources preserve evidence, notes hold current explanations, and plans retain decisions and outcomes. YAML frontmatter adds queryable metadata without requiring one domain schema for every vault. Stable paths, explicit links, and reviewable Git changes keep the material legible outside the CLI.

The Markdown files are authoritative. The catalog, QMD database, backlink view, graph traversal, and bounded Git index are derived and replaceable. Deleting one of those views removes a way to retrieve knowledge, not the knowledge itself.

Preserve evidence and plans as working records

Durable reasoning needs inspectable evidence. kb clip can read a public URL, saved HTML, rendered page, or a page already open in an authenticated browser. The capture documentation defines the supported routes. A capture writes readable Markdown beside localized assets and capture.json, whose manifest records where the material came from, how it was extracted, what was saved, and any warnings. “Complete” describes the selected page surface, not every hidden branch or future version of the site.

kb clip "https://example.com/article" --output articles
kb pdf "/absolute/path/to/document.pdf" --output articles

The resulting bundle is evidence, not final interpretation. A maintained note can cite several captures, record disagreement, and change when later evidence warrants it. The sources stay available for audit. This prevents an agent from silently replacing what a page said with what it now believes the page meant.

The plan-kb skill creates a normal Markdown file under kb/plans/ with an outcome, status, area, assumptions, dependencies, decisions, and verification method. The file grows during execution as agents record deviations, review findings, evidence, and the final result. Completed plans remain in Git as the history of the work. When a finding becomes a rule whose omission would make a future edit wrong, move that rule into the applicable AGENTS.md and retain the plan as its rationale.

Search and connect with bounded signals

An identifier, title, alias, path, tag, or quoted phrase should not depend on an embedding. Exact mode reads the live Markdown. The default hybrid mode combines those results with keyword and vector result orders from QMD, a local search engine for Markdown, while keeping exact identity matches first. Graph context and Git provenance remain separate evidence, so neither silently changes the primary text rank.

kb search "parser-v2" --root kb --mode exact
kb search "why does the parser reject this input?" --root kb \
  --tag architecture --where status=active --json
kb search "why did the parser change?" --root kb --history --json

--mode keyword uses QMD's local full-text index without loading an embedding model. Hybrid and semantic modes use a pinned local embedding model. KB reconciles every QMD hit with current Markdown before returning it, and applies metadata and tag filters to those live notes. Search modes remain explicit through --mode exact, --mode keyword, --mode semantic, and --mode hybrid.

Retrieval is bounded. The high-level kb search and KnowledgeBaseSession.search surfaces return at most 100 primary results and request at most 500 candidates from each QMD retrieval lane. Selective filters can discard stale or ineligible rows from that window. When those discards prevent KB from filling the requested eligible result set, KB marks the QMD lane degraded and the overall result partial instead of presenting the bounded approximation as complete. Scores are local ranking signals, not probabilities, and cannot be compared across modes.

Each note owns its outbound typed relationships in frontmatter. KB derives backlinks, inverse edges, and bounded traversal at read time, so parallel agents do not contend on one generated fact file. kb percolate <note> reports recurring concepts and missing-link candidates with inspectable support but writes nothing. An agent reads the cited notes before creating a reusable concept or relationship. Semantic similarity never creates an edge automatically.

Git provenance is opt-in. A search without --history performs no Git indexing. --history requests best-effort provenance, while --require-history rejects unavailable history or incomplete provenance for the selected notes. If one commit exceeds the 2,000-path detail limit, KB retains its identity and vault-local note associations, marks its co-change detail incomplete, and continues through later commits. Best-effort search reports that requested lane as partial.

Search finds candidates. Similarity does not establish that a passage is current, correct, or supported by its sources. The checked six-case rank-fusion fixture is a deterministic regression, not a real-corpus retrieval, latency, or RAG benchmark. The Markdown, cited captures, explicit relationships, and requested Git history supply the material a reader must inspect.

Adopt the smallest useful split

Start with a short inherited AGENTS.md path for rules whose omission would make an edit wrong. A small knowledge base may need only Markdown, Git, an index page, and ordinary file search. Add source capture when evidence keeps disappearing. Add metadata or hybrid search when file search stops answering the repository's questions. Add links and graph views only when the relationships themselves help people make decisions.

Treat the knowledge base as repository-adjacent durable memory. Authored Markdown and Git are the record; catalogs, indexes, embeddings, and graph views are replaceable ways to find and inspect it. Checks can validate structure, captures can preserve a selected surface, and similarity can suggest candidates. None of those mechanisms proves that a source is trustworthy or an explanation is still true. People and agents must revise the knowledge as the repository changes.