A coding agent needs two kinds of repository memory. It needs rules that govern the edit now, and it needs explanations and evidence that may help it reason. Mixing both into one automatically loaded prompt makes every task pay for history it may not need. Putting hard rules only in an optional knowledge base lets an agent miss them.
hraness/kb is an open-source knowledge base for coding agents that keeps those jobs separate. A scoped AGENTS.md file is the automatically loaded normative control plane: ownership, must and never constraints, and required checks. KB is the optional, pull-based knowledge plane for rationale, history, examples, evidence, plans, and linked neighboring decisions. KB may explain an applicable AGENTS.md rule, but it never silently overrides one.
The conceptual layout puts the control plane on the repository path and the knowledge plane in an ordinary Markdown vault. Scope hubs are optional, and application code imports neither KB nor its search index:
repository/
├── AGENTS.md # inherited root rules
├── packages/parser/
│ ├── AGENTS.md # scoped rules and checks
│ └── src/
└── kb/
├── scopes/
│ └── packages-parser--94a91e4eddfa.md
├── articles/<slug>/ # captured evidence and assets
├── notes/ # maintained synthesis
├── plans/ # decisions and verification
├── riffs/ # voice-preserving source thought
└── index.md # regenerated catalog
authored Markdown + frontmatter + wikilinks
├── kb list / kb links
├── kb datalog / percolate # in-memory DataScript view
└── kb search # derived local QMD indexMarkdown is authoritative in this map. The catalog, backlink view, DataScript database, and semantic index can be deleted and rebuilt. Obsidian can browse the same files, but it is a compatible editor rather than a runtime dependency. Git supplies review, history, and recovery for both rules and knowledge.
Separate rules from explanations
AGENTS.md belongs on the path to the code it governs. A root guide carries repository-wide policy; nested guides add the constraints owned by a package, product, or source boundary. Keep every load-bearing edit-time rule on that inherited path. If an edit would be wrong when the agent misses a sentence, that sentence does not belong only in KB. Agent docs hygiene explains how to keep that path scoped and checked.
KB holds material whose value depends on the question. A scope hub can explain why a parser rejects a tempting shortcut, link the plan that introduced the rule, preserve a source that supports it, and point to neighboring decisions. An agent pulls that prose when the task reaches the boundary. If a hub and an applicable guide disagree, the guide controls the edit and the hub needs repair.
A mapped hub declares optional frontmatter with type: agent-context and an exact repository-relative directory in scope. For packages/parser, the canonical hub at kb/scopes/packages-parser--94a91e4eddfa.md begins:
---
title: Parser context
type: agent-context
scope: packages/parser
---
# Parser contextIts guide at packages/parser/AGENTS.md carries the reciprocal marker before the two required headings:
<!-- kb:context scopes/packages-parser--94a91e4eddfa -->
# Contents
- `src/` – parser implementation and tests.
# Guidelines
- Keep every load-bearing parser rule here.kb agents identity <scope> emits the normalized scope, note ID and path, owning guide path, and exact marker without writing files. The canonical ID is scopes/<readable normalized slug>--<12-char SHA-256 prefix>. The bounded slug avoids mirroring a deep repository tree under scopes/, while the hash makes paths with the same leaf name, such as packages/parser and projects/parser, distinct. The full path remains in scope metadata. Moving a directory deliberately changes its identity, so the hub ID and reciprocal marker must change together.
Pull context, then check the mapping
kb context <path> --root kb --repo . returns the inherited guide chain from the repository root to the target and identifies the valid hubs mapped to that chain. It does not load hub prose. The agent receives the normative rules first, then opens the nearest useful hub only when the task needs its explanation.
From that hub, the agent can expand a bounded neighborhood with kb links, inspect backlinks, filter exact metadata, or use semantic search when vocabulary differs. The command is a routing aid, not an instruction loader for the whole vault. A small guide that needs no explanatory neighborhood can remain unmapped.
kb agents check validates both sides of every declared mapping: the hub type and exact scope, canonical slug-and-hash identity, reciprocal guide marker, and real guide and scope paths confined to the repository. Missing mappings on otherwise valid small guides are allowed. The check catches broken identity and unsafe paths; it cannot decide whether the prose is true or the rule is wise.
kb agents audit is advisory. It ranks individual guides and cumulative inherited context, then surfaces long bullets and exact duplicates for review. Length is not a correctness test: a long guide may encode necessary constraints, and a short one may be wrong. The audit identifies where attention may pay off without turning a word limit into policy.
Several systems converged on durable agent memory
This design direction did not begin with one recent proposal. Cognition's 2024 Devin release history described Knowledge that Devin could recall across future sessions by September 2024 and automatic Repo Knowledge from repository scans by November. On April 3, 2025, Devin 2.0 introduced Devin Wiki and Devin Search. Cognition launched the public DeepWiki service on May 5, then a DeepWiki Model Context Protocol server on May 22 for programmatic retrieval.
In April 2026, Andrej Karpathy published an LLM Wiki proposal with three layers: raw sources, an agent-maintained Markdown wiki, and an instruction schema. Its operations are ingest, query, and lint, with QMD suggested when the collection outgrows an index file. hraness/kb is not an implementation of Cognition's products, and the resemblance does not establish direct lineage. The sequence shows convergence on one pressure: useful reasoning must become a durable artifact before a session ends.
Keep the files authoritative and portable
A knowledge base earns trust differently from a chat transcript. Its records need stable paths, reviewable changes, and a format that remains legible when the current agent is gone. Plain Markdown, YAML frontmatter, and explicit wikilinks meet that bar with little codebase coupling. An agent can begin with index.md and ordinary file tools or use the KB commands and skills. Neither path requires a hosted database or a proprietary document format.
Directory names express editing authority without becoming a framework. Captured articles preserve what a source said. Notes hold current synthesis. Plans record intended work, evidence, and outcomes. Riffs preserve a speaker's claims and uncertainty. Scope hubs organize optional repository context. The application under development does not import KB, and every derived view remains replaceable.
Make evidence capture an auditable write path
Durable reasoning needs inspectable evidence. kb clip can read a public URL, saved HTML, rendered page, or the page already open in an authenticated browser. The capture documentation defines layered extraction routes. A capture writes readable Markdown beside localized assets and capture.json, whose manifest records the source URL, attempted routes, chosen extractor, completeness state, counts, warnings, and artifact hashes. “Complete” describes the selected bounded surface, not every hidden branch or future version of the page.
PDFs use the same durable bundle for a local path or public HTTP(S) URL. kb pdf sends remote input through a DNS-pinned acquisition boundary that denies private networks, then removes sensitive URL parameters from saved provenance. Local and remote capture preserve the original bytes, infer headings from native layout, extract bounded images, and use local optical character recognition for scans and screenshots.
kb pdf "/absolute/path/to/document.pdf" --output articles
kb pdf "https://example.com/document.pdf" --output articlesThe 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 boundary prevents an agent from silently replacing what a page said with what it now believes the page meant.
Use exact structure before semantic similarity
Some retrieval questions have exact answers. kb list parses frontmatter such as type, status, area, dates, aliases, and tags into bounded scalar, list, and nested-object values. It can combine repeated filters with AND semantics, follow dotted metadata paths, match tags case-insensitively, and sort with a stable path tie-breaker. The parser makes a query reproducible; it does not impose one domain schema on every vault.
kb list --root kb --where type=plan --where status=in-progress --sort area --json
kb links scopes/packages-parser--94a91e4eddfa --root kb --direction both --depth 2 --limit 25 --jsonWikilinks answer another exact question: which relationships did an author state in prose? The scanner resolves exact and relative targets or a unique basename, and reports broken or ambiguous links rather than guessing. kb links walks an explicit number of incoming and outgoing hops with a result limit and cycle handling. Backlinks reverse those resolved edges at read time. Traversal never expands through semantic similarity, so an agent can inspect a bounded neighborhood without loading the vault.
Let concepts and relationships percolate
A useful vault eventually contains ideas that recur across source boundaries. Keeping every occurrence as an isolated tag makes the pattern hard to inspect; moving all graph state into one generated file gives parallel agents a permanent merge conflict. KB uses a smaller convention. A reusable concept is an ordinary Markdown note with type: concept. A note stores only the typed outbound assertions it owns:
---
type: note
tags:
- local-first
relations:
supports:
- notes/durable-agent-memory
contrasts-with:
- notes/conversation-history
---
# The write path
The local-first write path supports durable agent memory because ...Predicates use lower-kebab-case and targets use exact vault-root note IDs. The explanatory sentence matters: frontmatter makes an assertion queryable, but it does not supply its reason. Inverse edges, backlinks, transitive paths, and shared-concept neighborhoods are derived at read time. KB does not inject them into another note.
kb percolate <note> reviews repeated tags without concept notes, notes that share ideas but lack a contextual edge, exact unlinked title or alias mentions, and relationship-hygiene findings. Each result carries inspectable support; relationship candidates count independent shared tags or concept neighbors, not both endpoints of one match. The command is read-only. An agent opens the cited notes, promotes only concepts likely to be reused, and authors a relationship only when the prose or evidence establishes it:
kb percolate notes/write-path --root kb --limit 25 --json
kb note create notes/durable-agent-memory \
--root kb --title "Durable agent memory" --type concept \
--body-file /path/to/reviewed-concept.md
kb relation add notes/write-path supports notes/durable-agent-memory \
--root kbProject Markdown into Datalog
KB projects the current notes into an immutable in-memory DataScript database for each structural query. Notes, tags, typed metadata leaves, wikilinks, and relationship edges receive stable semantic string identities. DataScript's numeric entity IDs never appear in the public result. kb datalog can then express joins, aggregates, predicates, and recursive paths that would be awkward as a collection of bespoke commands:
The engine choice is intentionally narrow. Datalevin getting-started guide and CozoDB documentation are compelling when the graph database itself owns durable state. KB already has a durable, mergeable source of truth in Git, so adding native storage, a JVM, migrations, or a second synchronization protocol would solve the wrong problem. DataScript supplies recursive Datalog over a temporary relation and then gets out of the way.
Raw queries run in a disposable one-shot subprocess with a 2-second default deadline, a 5-second ceiling, and bounded inputs and results. Fact projection spends its limit while it walks nested metadata, and the parent validates the result again before returning it to the CLI. An accidental Cartesian product therefore ends as a typed budget error or a terminated child process instead of occupying the agent indefinitely.
DataScript 1.7.8 evaluates recursive rules top-down. A rule that walks relationships which may cycle must carry an explicit remaining-depth argument and decrement it on every recursive hop; an unbounded recursive rule over a cycle is contained by the subprocess deadline. For ordinary path questions, kb links already provides bounded traversal and cycle handling.
kb datalog '[
:find ?source ?target
:where
[?edge :edge/predicate "supports"]
[?edge :edge/source ?source-ref]
[?source-ref :note/id ?source]
[?edge :edge/target ?target-ref]
[?target-ref :note/id ?target]
]' --root kb --limit 50 --jsonThe database is never committed, shared, or treated as storage. DataScript's JavaScript persistence serializes a complete database; using that snapshot as a repository artifact would create the central merge hotspot this design is meant to avoid. Rebuilding from Markdown keeps facts readable, diffs local to the note that owns them, and the query engine replaceable. During parallel work, each lane can run kb check --no-catalog without rewriting index.md; the integrating agent performs one final refresh.
Exact structure cannot find a note whose author used unexpected language. For that lane, hraness/kb embeds QMD, a local search engine for Markdown. kb index builds or refreshes a derived database in a local cache outside the vault. kb search checks for changed Markdown, then returns semantic candidates joined to authored metadata, tags, backlinks, and edge counts. Keyword BM25 search remains available with --mode keyword when exact terms fit better.
A vector score means two passages occupy a nearby region in an embedding model's representation. It does not mean the passage is current, correct, or supported by its sources. Use semantic results to find candidates, metadata and Datalog to narrow them, links and typed edges to inspect stated relationships, and the Markdown plus cited captures to verify the answer. QMD remains optional and local; deleting its index does not delete knowledge.
Keep plans durable and promote rules to AGENTS.md
A plan shown only in chat has the same session boundary as the reasoning that produced it. The plan-kb skill writes a normal Markdown file with an outcome, status, area, assumptions, dependencies, decisions, and verification method. During execution, the same plan accumulates deviations, review findings, command evidence, and the final result. Completed plans remain as history. A finding that becomes a load-bearing edit rule moves into the applicable AGENTS.md; its rationale and evidence may stay linked from the scope hub.
hraness/kb also ships six Agent Skills that preserve the same file contract. save-url-kb selects a URL acquisition route and records completeness; save-pdf-kb preserves a PDF's text, images, bytes, and provenance; query-kb chooses exact metadata, Datalog, graph, or semantic retrieval; percolate-kb reviews changed notes for reusable concepts and evidence-backed relationships; refresh-kb regenerates the catalog and reviews graph diagnostics; and plan-kb keeps execution knowledge durable. The agent workflow documentation defines how these skills meet the CLI contracts across agent runners. Skills guide writes and retrieval; they do not make application code depend on KB.
Adopt the smallest useful split
Start with a short inherited AGENTS.md path for rules whose omission would make an edit wrong. Add a scope hub only when its rationale, evidence, plans, or linked decisions deserve pull-based retrieval. A small KB vault may need only Markdown, Git, an index, and ordinary file search. Add typed relationships, Datalog, metadata queries, graph traversal, QMD, browser capture, or PDF ingestion only when the simpler layer stops answering the repository's questions.
This is a file-backed control plane paired with an optional knowledge plane, not autonomous memory. Checks validate structure, not truth. Capture preserves a selected surface, not the source's trustworthiness. A typed edge records an authored assertion, not proof; Datalog derives answers, not facts; and semantic similarity supplies candidates, not conclusions. The design works only while people and agents keep hard rules in scope and revise the concepts, evidence, and explanations those rules point to.