Building Agent Knowledge Bases That Actually Scale

This is part eight in a series about managing the growing pile of skills, scripts, and context that AI coding agents depend on. Part one introduced progressive disclosure. Part two unified your local assets across platforms. Part three added persistent memory. Previous parts addressed teams, distributed stashes, and community knowledge.

This one is about a different problem: knowledge accumulation.

You start a new research area — say, LLM inference optimization. You read papers. You take notes. You save PDFs. Your agent writes summaries, discovers connections, asks follow-up questions that lead to more notes. Six weeks later you have a pile of markdown files, half-digested papers in a downloads folder, and a memory that says "we covered KV cache quantization somewhere." You search for it. You get three files with different partial takes on the same topic. None of them have the answer you need.

This isn't a storage problem. You have all the information. It's a structural problem — and that's what akm's multi-wiki support is built to fix.

Karpathy's LLM Wiki Pattern

In a GitHub gist, Andrej Karpathy described a pattern for maintaining a markdown knowledge base that a human and LLM build and maintain together. The core idea is deceptively simple: a structured directory of markdown pages, with an agent responsible for synthesizing incoming information into those pages over time.

The insight is that agents are genuinely good at certain things that humans find tedious. Summarizing a 40-page paper into a two-paragraph page entry. Finding the connection between a new paper and something already in the knowledge base. Keeping a log of what was added and why. Updating an existing page when new information contradicts or extends it.

What agents are not good at: maintaining invariants. An agent won't reliably enforce slug uniqueness. It won't regenerate an index consistently. It will sometimes overwrite a source file you meant to keep immutable. It loses track of what's been ingested when sessions end.

So you need a division of labor. The agent does the synthesis. The tooling enforces the invariants. That's the gap akm's wiki support fills.

The Problem: Knowledge That Accumulates and Gets Lost

Most developers hit this in one of two ways.

The first way: you import a file as a knowledge asset (akm import ./paper.md) and your agent reads it directly. That works fine for one or two documents. At ten documents, the agent is loading full text into every relevant session. At thirty documents, you're spending tokens on context you don't need, and the agent is trying to mentally synthesize relationships across thirty separate files per session. Nothing is connected. Nothing is indexed.

The second way: you ask your agent to "take notes" in a notes.md file. The file grows. It becomes a wall of text with no structure. Searching it is grep. Updating it means the agent has to read the whole thing before writing anything. After a few sessions the agent starts ignoring sections it wrote two weeks ago because they're below the fold.

Both patterns fail in the same way: there's no structural home for the knowledge. No schema that says what a page is. No index that makes things findable. No log that tracks what happened. No separation between raw sources and synthesized pages.

How akm's Multi-Wiki Works

A wiki in akm is a named subdirectory under ~/akm/wikis/. Each wiki has a fixed structure:

~/akm/wikis/
  research/
    schema.md       # per-wiki rulebook: page kinds, voice, contradiction policy
    index.md        # catalog of all pages — regenerated by akm index
    log.md          # append-only activity log
    raw/            # immutable ingested sources (never edit these)
    attention.md    # a synthesized page
    transformers/
      architecture.md

You create a wiki with one command:

akm wiki create research

That scaffolds the directory, stubs out schema.md with sensible defaults, creates empty index.md and log.md, and makes the raw/ directory. You're not starting from a blank directory — you're starting from a structural contract.

The schema.md file is important. It's where you define the rules for this particular wiki: what page kinds are allowed, what the voice should be, how contradictions are handled, what the minimum viable page looks like. You edit it once when you create the wiki, and the agent reads it at the start of every ingest session. It's the wiki's constitution.

Walking Through a Real Workflow

Say you're building a research wiki on transformer architectures. You have a paper PDF, some notes from a talk, and a few bookmarked articles.

Start by bringing in the raw sources:

akm wiki stash research ./attention-paper.pdf --as attention
akm wiki stash research ./transformer-scaling-notes.md --as scaling-notes
echo "# Key quote from Sutton talk" | akm wiki stash research -

The stash command copies each source into raw/ with a unique slug. If you try to stash the same slug twice, it errors rather than overwriting. That's one of those invariants the agent can't reliably maintain — akm handles it.

Now ask your agent to start the ingest workflow:

akm wiki ingest research

This prints a step-by-step recipe for what the agent should do next. Something like: read schema.md to understand the page structure, check index.md to see what pages already exist, read each unprocessed file in raw/, synthesize content into pages using Write or Edit, update index.md, append a summary to log.md. The command itself writes nothing — it just prints the workflow. Execution is entirely the agent's job, using its native file tools.

After the agent runs the ingest workflow:

akm wiki pages research
# → research/attention.md   "Self-attention mechanism and complexity analysis"
# → research/transformers/architecture.md   "Encoder-decoder structure, residual connections"

Later, when you want to check the health of the wiki:

akm wiki lint research

Lint runs deterministic structural checks: orphan pages (not in index.md), broken xrefs in frontmatter, missing descriptions, raw files that appear uncited in any page, and whether the index is stale relative to the directory contents. These are checks that require counting and comparing file state — exactly the kind of thing agents do inconsistently.

The "akm Surfaces, the Agent Writes" Principle

This division of labor is worth making explicit, because it determines what belongs in akm and what doesn't.

akm handles operations that require invariants an agent can't reliably enforce across sessions:

• Scaffolding (ensures required files exist with the right names)
• Source import (unique slugs, never overwrites, immutable raw/)
• Lint (deterministic structural checks against file system state)
• Index regeneration (consistent format, triggered by normal indexing)
• Workflow printing (a recipe the agent can follow without reinventing it)

The agent handles everything that requires judgment:

• Writing and updating pages
• Synthesizing connections between sources
• Deciding what a page should say and how to structure it
• Appending meaningful log entries
• Adding xrefs in frontmatter

The reason this split matters: agents are good at synthesis and bad at reliability. If you ask an agent to "update the index," it will sometimes do it correctly, sometimes produce a subtly wrong format, and sometimes forget. If you ask it to write a page on attention mechanisms from three source documents, it will do that well every time. The tool enforces the boring, brittle parts so the agent can focus on what it's actually good at.

There are no unconditional LLM calls inside akm for wiki operations. The wiki commands are pure file operations, SQLite, and structural analysis — fast, deterministic, and usable offline. (akm does ship bounded opt-in LLM calls for other workflows, like akm distill and akm curate, gated behind llm.features.* flags that are all off by default. But the wiki tooling itself never touches an LLM.)

akm wiki search vs akm search --type wiki

Once you have a few wikis, you'll use two different search paths depending on what you need.

akm wiki search research "attention mechanism" runs a scoped search within the research wiki only. Use this when you know which wiki holds the answer and you want precision — no noise from other wikis or other asset types. The results are page refs with descriptions, scoped to research/. Raw sources under raw/ plus the wiki root infrastructure files schema.md, index.md, and log.md are excluded from the search index and never appear as search hits.

akm search --type wiki "attention mechanism" runs the full stash-wide search across all wiki pages. Use this when you're not sure which wiki something lives in, or when you want to see if anything from multiple wikis is relevant to a task before loading anything.

In practice: scoped search during active work in a specific domain, wide search when starting a new session or doing cross-domain research. Wiki pages participate in the same FTS5 scoring pipeline as every other asset type, so --type wiki is not a second-class citizen — a highly relevant wiki page will outrank a mediocre skill in a general search.

Practical Example: Building a Research Wiki

Here's the complete workflow for setting up and using a research wiki from scratch.

Initial setup:

akm wiki create research
# Edit wikis/research/schema.md to define your page kinds
# (technical-summary, comparison, open-question, etc.)

Bring in sources as you find them:

akm wiki stash research ./papers/attention-is-all-you-need.pdf --as attention-2017
akm wiki stash research ./papers/flash-attention-v2.pdf --as flash-attention-v2
akm wiki stash research ./notes/scaling-laws-talk.md --as scaling-laws-notes

Run ingest when you're ready to synthesize:

akm wiki ingest research
# Agent reads the recipe, reads raw/ files, writes pages, updates index, logs activity

Check what exists:

akm wiki pages research
akm wiki show research

Search when working on a related task:

akm wiki search research "KV cache memory"
# Returns: research/attention.md, research/flash-attention/optimization.md

Lint before a long agent session to catch structural drift:

akm wiki lint research
# Orphans: none
# Broken xrefs: research/flash-attention/optimization.md → research/kv-cache.md (missing)
# Stale index: yes (run akm index)

Fix the stale index:

akm index
# Rebuilds SQLite search index, regenerates wikis/research/index.md as a side effect

At the end of a few weeks, you have a structured, searchable knowledge base. Your agent can load specific pages by ref instead of reading all thirty raw sources every session. You can run lint any time to catch drift. The log tells you what was synthesized and when. The raw sources are still there if you ever need to re-derive something from primary material.

What This Isn't

Multi-wiki is not a document management system. If you want to store and retrieve original documents, akm import and the knowledge type already do that.

It's not a notes app. Single notes go in memories. Reference material goes in knowledge. Wikis are specifically for synthesized, structured knowledge that grows over time through an active ingest process.

It's also not autonomous. akm prints the ingest recipe; your agent runs it. If you want fully automated ingestion, you'd wire up a workflow that calls akm wiki ingest, then asks the agent to execute the printed steps. The wiki tooling is the substrate, not the automation layer.

Getting Started

Multi-wiki has been available since akm 0.5.0. If you're already using akm, upgrade and try:

akm wiki create research
akm wiki list

The Getting Started guide covers initial setup if you're new to akm. The wiki commands are available immediately once you have a stash configured.

If you're working in a domain where knowledge accumulates — research, security analysis, architecture decisions, competitive analysis — give it a run and see if the structure helps. The repo is at github.com/itlackey/akm. Questions and feedback in the issues.