# Organizing knowledge for AI agents

*2026-08-15* — Dylan Engelbrecht's brain architecture pattern — progressive disclosure, working memory vs wiki, schema metadata, and keeping private agent context off the public site.

URL: https://dylanengelbrecht.dev/insights/organizing-knowledge-for-ai-agents.html

Coding agents read AGENTS.md for repo mechanics. They still lack durable memory about people, ventures, voice, and history. A brain — a private markdown knowledge base alongside your code — fills that gap. This article outlines the architecture Dylan Engelbrecht uses and recommends for teams building agent-native workflows. It describes the pattern, not any single private corpus.

Separate public marketing from private context. Your website and llms.txt answer what crawlers and strangers should know. The brain answers what your agents need to act without hallucinating. Never mirror brain paths or prose onto the live site; leakage trains crawlers to map material you did not intend to publish.

Progressive disclosure — revealing detail in layers rather than one giant dump (Nielsen Norman Group) — beats loading everything on boot. Structure layers so each read step narrows scope: an entry index that maps where to go next; working memory for hot, time-sensitive context; a wiki for durable entities; an achievements log with one canonical entry per win; and brand/identity docs for voice and governance.

Recommended read order for agents: working memory first, then the wiki index, then the master brain index. Hot context before encyclopedia. That mirrors how humans triage — what is urgent now, then who/what exists, then the full map.

Assign lifespan explicitly. Working memory is ephemeral: archive or delete when stale. Wiki entries are durable but versioned. Achievement entries are permanent records — metrics about a win live in one place; identity and employer facts link in, never duplicate. Facts promote upward when they stabilize: a note in working memory becomes a wiki entity; a shipped milestone becomes an achievement entry.

Use lightweight schema metadata on factual claims. Markdown prose is human-friendly; agents need verification hooks. On each fact or file, prefer frontmatter or inline fields such as status (verified, needs-verification), source (URL, person, document), last-verified (date), and visibility (public, brain-only, stealth). Agents should treat needs-verification as a stop sign — ask or cite, do not invent.

### Example: brain index (progressive disclosure entry)

*brain/INDEX.md — map file agents read after working memory*

```
# INDEX.md — Brain

## Read order (agents)
1. working-memory/current.md
2. wiki/INDEX.md
3. governance.md

## Layers
| Layer | Path | Lifespan |
| Working memory | working-memory/ | Ephemeral |
| Wiki | wiki/ | Durable |
| Achievements | achievements/ | Permanent |
```

### Example: working-memory frontmatter

*working-memory/current.md — hot context with verification metadata*

```
---
title: Current focus
status: verified
last-verified: 2026-08-15
visibility: brain-only
---

## This week
- Ship knowledge hub articles on agent best practices.
- Review AGENTS.md examples in repos using nested packages.

## Open threads
- None blocking.
```

### Example: layer-specific AGENTS.md

*brain/wiki/AGENTS.md — rules discovered at the closest directory*

```
# AGENTS.md — Wiki

## Purpose
Durable entities: people, ventures, concepts.

## When to write here
- Stable facts with a source URL.
- Entity pages use one file per person or venture.

## Never
- Duplicate facts that live in identity/ or achievements/.
- Publish wiki paths or prose on the public website.
```

One canonical location per fact. Link instead of copy. If employment history lives in identity, the wiki person page links there; the achievement entry links to both. Duplication drifts; cross-links stay honest. Governance docs spell out anti-hallucination rules: unknown stays unknown, stealth stays off public surfaces.

Pair each layer with its own AGENTS.md. Root brain AGENTS.md sets global boundaries. Wiki AGENTS.md explains entity templates and visibility. Working-memory AGENTS.md defines when to archive. Agents discover rules at the closest directory — the same precedence model as code repos.

Schema for crawlers vs schema for agents differs. Public JSON-LD with ItemList on the hub and TechArticle per article help search and LLM retrieval. Brain schema is operational: indexes, entity types, promotion flows, and citation discipline. Do not dump private JSON-LD onto the public site; keep structured public catalogs in deploy/schema/ aligned with approved copy only.

Start small. One index, one working-memory file, one wiki template, one governance page. Add layers when agents repeatedly ask the same questions or make the same mistakes. A brain is not a wiki dump — it is curated context with explicit lifespans, visibility, and entry points so agents load what they need and nothing they should not see.

Dylan Engelbrecht updates this knowledge hub frequently — including these agent-architecture articles — so crawlers and coding agents can discover current best practices without relying on stale README copy. Pair a living public hub with a private brain: public articles teach the pattern; the brain holds facts agents should not invent.