Build a persistent knowledge base your AI agents can actually use

01 Diagnose the failure as a context gap before you touch the model.

When the agent isn't doing what you want, the first investigation is the context, not the prompt and not the model. Context, not capability, is the bottleneck Frontier models reason well in general. They fail on specifics they were never told: how this codebase is organized, what the team's conventions are, which approaches a past decision already ruled out. Each missing piece produces one wrong answer.

"When the agent isn't doing what you want, it's usually a problem with context — you've underspecified or there's just not enough information available."

· Sherwin Wu, Lenny's Podcast, 2026-04-28 · “When the agent isn't…”

The shift this forces is from prompt engineering, which is volatile, to context engineering, which is durable. Context engineering beats prompt engineering for marketing AI workflows Standing up the tool takes a week. Making it work well takes a quarter and a half, and that work is almost entirely about the context substrate, not the prompts.

"The initial setup took maybe a week or so. But getting it actually to work well? That took a quarter and a half. Two full-time people reviewed every output, every single day. We kept finding gaps in the training documents."

· Aatir Abdul Rauf, LinkedIn, 2026-04-10 (scrape date) · “Context engineering beats prompt…”

02 Reject the ask-answer-forget loop. The knowledge base is the alternative.

The default way people use AI is a cold start every time: ask, get an answer, forget it, ask again tomorrow. Most people are still using AI like this: ask → answer → forget That loop rebuilds the same synthesis over and over and resolves the same contradictions over and over, because none of it ever lands anywhere durable.

"Most people are still using AI like this: ask → answer → forget."

· Alok Yadav, LinkedIn, 2026-04-10 · “Most people are still…”

The knowledge base inverts the loop. The agent writes a synthesis page once, links it to the raw sources, lints it for contradictions, and on the next session reads the page instead of re-grounding from scratch. An LLM should maintain a wiki, not re-derive knowledge per query This is the Karpathy LLM-wiki pattern: replace stateless retrieve-and-forget with a persistent wiki the agent owns and edits.

"Traditional RAG rediscovers knowledge repeatedly rather than accumulating it. The LLM builds and maintains a persistent wiki instead of just retrieving documents. Knowledge compiles once and stays current, not re-derived per query."

· Andrej Karpathy, LLM Wiki gist, 2026-04 · “An LLM should maintain…”

The deeper reason to build this now: the LLM platform is becoming the surface through which work gets done, and durable, agent-readable context is the thing that survives that shift. LLM platform is the new OS, agents are the new apps, MCP registries are the new app stores

"The LLM platform is the new OS. Domain-specific agents are the new apps. MCP registries are the new app stores."

· Mark Petty, Gartner (G00828648), 2026-02-27 · “LLM platform is the…”

03 Build it in three layers so synthesis and source never collide.

The structure is what keeps the base from rotting. Three layers, each with one job.

Raw is the source of truth and stays untouched. Synthesis is compression plus cross-reference, not transcription. A synthesis page that mirrors its raw source verbatim is doing no work. The whole point of the layer is that the agent skims the synthesis when it needs the gist and drops to the raw file when it needs the exact words.

04 Define four operations the agent runs against the base.

Name the operations explicitly in the constitution so the agent has a fixed verb for each kind of work.

1. INGEST. Source becomes raw/{subdir}/{slug}.md with frontmatter, then stub a synthesis page if warranted, then append a log entry.
2. QUERY. Read the index catalog, read one to three relevant pages, extract and cite paths. If the answer is not in the base, say so. Do not fabricate.
3. LINT. Walk every page for orphans, contradictions, stale claims, missing pages, naming drift, schema violations, index mismatches. Fix high-impact in place, leave low-impact documented.
4. INDEX plus LOG. The index is the content catalog, one line per page, kept under 200 lines. The log is the chronological append-only timeline.

05 Write everything down. Treat the substrate as the work, not a record of it.

The discipline that makes the base trustworthy is refusing to trust working memory for anything that matters. Files first, never vibes. Every interview, every competitive datapoint, every claim you might one day put in a deck goes into a file with a category, a date, and a source, so synthesis becomes a query, not a recollection. The substrate is the work. Files first, vibes never. The substrate IS the work.

This is the same move Tiago Forte calls a Second Brain: the brain is for having ideas, the system is for storing them, and AI compounds the stored layer on demand. Brains are for having ideas, not storing them, externalize knowledge so AI can compound it for you

"Our brains are for having ideas, not storing them — an external, organized knowledge system compounds over time and becomes the foundation for creative output, especially when AI can now search, synthesize, and surface that knowledge on demand."

· Tiago Forte, Building a Second Brain · “Brains are for having…”

06 Make the context rich and specific, not thin and generic.

Depth of context, not sophistication of the agent, is the deciding factor. A simple agent reading dense, domain-specific material beats a complex agent reading boilerplate every time. Simple agents reading rich, specific context outperform complex agents reading thin context Generic context gets generic output. Worse, a sophisticated agent over thin context produces confidently wrong results, because the chain amplifies whatever the thin context implied.

"Simple agents reading rich, specific context will outperform complex agents reading thin context every time."

· Maja Voje + Benjamin Gibert, GTM Strategist, 2026-05-01 · “Simple agents reading rich,…”

The gap is measurable. Among 200 GTM operators surveyed, 93% of advanced users had detailed company context built into their workflow as a foundation, versus 72% of task runners, a 21-point gap that separates teams reporting previously impossible work from teams running one-off prompts. Among 200 GTM operators surveyed, detailed company context adoption separates systemic AI builders from task runners by 21 percentage points. The first pull request on a new agent should be a context bundle, not a prompt.

07 Give each context document a named owner.

A document with no owner decays. Products change, competitors move, ICP shifts, and an unmaintained doc goes trust-negative within a quarter. Ownership turns the artifact into living substrate, and a well-built document then powers many workflows at near-zero marginal cost. Context documents are reusable battery packs that need named owners

"Context documents need clear owners. Someone has to maintain, update, and ensure they're accurate. And since they are reusable, those context documents act like battery packs that can power multiple AI and agentic workflows."

· Aatir Abdul Rauf, LinkedIn, 2026-04-10 (scrape date) · “Context documents are reusable…”

One ICP doc, one positioning doc, one competitive map can feed outbound email, competitive analysis, and launch scripts. Among 200 GTM operators surveyed, detailed company context adoption separates systemic AI builders from task runners by 21 percentage points. The economics only compound when each document has someone accountable to a refresh cadence. Add an owner column to the index.

"The top GTM AI tool stack in 2026 is Claude + CRM + orchestration. These tools are not competing. They are combining."

· Kyle Poyar, Claude for GTM Pulse Report 2026 · “Among 200 GTM operators…”

08 Run lint on a cadence. Without it the base rots into a write-only pile.

The wiki pattern works only when the operator commits to lint passes. An LLM should maintain a wiki, not re-derive knowledge per query Without lint the base becomes write-only, and a write-only base degrades agent quality instead of improving it. Encoded misinformation is worse than no encoding. When the agent isn't doing what you want, fix the context, not the model

A lint pass walks every page and checks for orphans, contradictions, stale claims, missing pages, naming drift, schema violations, and index mismatches. The output is a findings file. Fix the high-impact items in place. Document the low-impact ones and move on. A lint pass that fixes nothing and files no findings is theater. Watch the trend: lint reports should show declining drift over time, not growing.

09 Close the feedback loop. A log of what happened is not a system that learns.

Capturing what the agent did is logging. Learning needs a signal of whether what it did was good, bound to the specific record. A trace alone teaches nothing; learning requires feedback attached to the trace A trace alone teaches nothing.

"A trace tells you what happened. It does not, by itself, tell you whether what happened was good. To learn from traces, you need feedback attached to them."

· Harrison Chase, LangChain blog, 2026-05-05 · “A trace alone teaches…”

The operational move is to mine session transcripts for patterns worth keeping, then promote those patterns back into the base, into pages, conventions, the constitution, so the next session inherits what the last one figured out. Close the feedback loop by mining session transcripts for patterns to promote into config Promotion is a reviewable, reversible edit, not a one-off tweak that gets forgotten on the next change.

"Close the feedback loop — mine session transcripts for patterns to promote into config."

· Eugene Yan, eugeneyan.com, 2026-05-03 · “Close the feedback loop…”

10 Keep a human on verification. The base produces drafts; you decide what is true.

Across PMM, evals, frameworks, and research, operators converge on one role split: the substrate runs the inner loop of execution and retrieval, and humans run the outer loop of alignment and taste. Substrate runs the loop; humans run alignment and taste The human is not a reviewer in every step. The human owns the call about whether a synthesized page is right in this specific context.

"You can outsource your thinking, but you can't outsource your understanding."

· Andrej Karpathy, Sequoia AI Ascent 2026 fireside, 2026-04-30 · “You can outsource thinking,…”

This maps directly onto the anti-fabrication rule the base must enforce: every claim traces to a raw source, code, memory, or the operator's own words. Files first, vibes never. The substrate IS the work. If a claim does not trace, the agent writes "unverified" and stops. Verification, not production, is the irreplaceable human job. Verification, not execution, is the irreplaceable human job

11 Wire the base into every session and keep it portable.

The base only helps if the agent reads it before working. Import the schema and the index into your agent's startup context so they expand inline at session start, without burning tokens on the full constitution every time. A compressed agent-facing distillation, roughly 50 to 80 lines, is what gets imported. The full constitution stays on disk for lint passes and rule changes.

Keep the base in plain markdown the agent owns, not locked inside one vendor's harness. Frontier labs are training native interface preferences directly into model weights, so the more your context lives inside a single harness, the more you pay when the model or the tool changes. Frontier labs are baking native harness preferences into model weights, not layering them on top

"frontier models will resemble appliances, not general platforms"

· Drew Breunig, Overfitting the Harness, 2026-05-10 · “Frontier labs are baking…”

A harness-independent markdown base is the hedge. Any agent, Claude Code, codex, cursor, reads the same files. When the next model lands and eats half your scaffolding, the context survives because it was never welded to the tool. Build for the next model, not the current one