Build a team knowledge base through conversation

Knowledge base turns conversations into shared team context. Teach the agent about people, systems, decisions, and standing preferences. Three server tools read, search, and write human-readable markdown pages; a conventions skill shapes each write; and a daily schedule merges duplicates and rebuilds the index. A fresh session retrieves what an earlier conversation captured.

Use this project when people should curate organizational knowledge through chat. Use Codebase wiki when merged PRs should maintain feature documentation instead.

Browse the knowledge base source.

Keep shared knowledge on the filesystem

The knowledge base lives outside any session workspace, in .agent-serve/wiki/ by default. KNOWLEDGE_BASE_DIR overrides the location, and the tools resolve it on every call, so tests and evals can point the same code at a temp directory.

The store enforces its own safety:

• Page ids are one to three lowercase kebab-case segments, so a page id can't escape the wiki directory.
• Pages cap at 64 KiB. Oversized writes fail with instructions to split the page.
• wiki_write replaces whole pages. The instructions require reading a page before updating it, so rewrites carry existing facts forward.

Every page is plain markdown. You can open the wiki in an editor, review it in a PR, or grep it.

Follow a fact through the agent

1. You tell the agent something durable: a system, an owner, a standing preference.
2. The instructions require a wiki_search before claiming knowledge and a wiki_write after learning something worth keeping.
3. The wiki-conventions skill picks the page id (staging-database, people/jane-doe), the page shape, and the dated fact format.
4. The tool writes the page under the durable wiki root and returns whether it created or updated the page.
5. A later session, on any channel, finds the fact with wiki_search and cites the knowledge-base page in its answer.

Ephemeral chatter stays out. The instructions tell the model to skip one-off questions and to ask before saving anything borderline.

Map the knowledge-base files

File	Purpose
agent/agent.ts	Selects the cloud runtime and model.
agent/instructions.md	Sets the read-before-answer and save-after-learning policy.
agent/lib/wiki-store.ts	Validates page ids, lists, reads, writes, and searches the knowledge base.
agent/tools/wiki_read.ts	Reads one page or lists every page with titles and timestamps.
agent/tools/wiki_search.ts	Searches titles and bodies with per-page match lines.
agent/tools/wiki_write.ts	Creates or replaces a page and reports created versus updated.
agent/skills/wiki-conventions.md	Names pages, shapes them, and dates every fact.
agent/schedules/gardener.md	Merges duplicates, rebuilds the index, and flags stale facts daily.
agent/lib/wiki-store.test.ts	Unit-tests slug safety and store round-trips.
agent/storage.ts	Persists sessions and events with cursorHostedStorage.
evals/evals.config.ts	Caps eval run concurrency.
evals/knowledge.eval.ts	Seeds a temp knowledge base and gates recall, save, and no-write decisions.

There is no authored channel, MCP connection, subagent, hook, A/B experiment, or custom storage. The wiki directory is the durable state.

Prepare the example

You need:

• Node 22.13 or newer.
• An agent-runtime credential for model turns.

Nothing else. The wiki is created on first write.

Validate the surface

agent-sdk validate --dir examples/knowledge-base
agent-sdk info --dir examples/knowledge-base --json

The manifest should report three server tools, one skill, and one schedule.

Exercise the store without a model turn

agent-sdk call wiki_write \
  --dir examples/knowledge-base \
  --input '{"page":"staging-database","content":"# Staging database\n\n- Port: 6432 (recorded 2026-07-19)\n"}'

agent-sdk call wiki_search \
  --dir examples/knowledge-base \
  --input '{"query":"6432"}'

agent-sdk call wiki_read --dir examples/knowledge-base --input '{}'

Invalid page ids fail fast. Try {"page":"../escape"} and the tool returns the validation error instead of touching the filesystem.

Prove recall across sessions

agent-sdk dev examples/knowledge-base

Teach it something in the playground:

Remember: our staging database is Postgres at staging-db.internal.example.com, port 6432 via PgBouncer. Jane Doe owns it.

The trace shows the conventions skill load, then wiki_write calls for staging-database, people/jane-doe, and index. Start a new session and ask:

What port does our staging database use, and who owns it?

The fresh session finds the answer with wiki_search and wiki_read and cites the pages. The conversation history is empty; the wiki is the source of truth.

Run the gardener

The gardener schedule fires at 06:00 UTC and rewrites the wiki for consistency: merge near-duplicate pages, rebuild index, and flag facts older than 90 days. Under agent-sdk dev, timers don't auto-fire. Trigger it by hand:

curl -s -X POST http://127.0.0.1:3000/knowledge-base/v1/dev/schedules/gardener

Run the evals

agent-sdk eval --dir examples/knowledge-base --list
agent-sdk eval --dir examples/knowledge-base knowledge/recall

The eval file seeds a temp directory through KNOWLEDGE_BASE_DIR inside the cases, so the durable knowledge base never sees test data. knowledge/recall proves the fact comes from disk, not the conversation. knowledge/save gates the write decision, and knowledge/no-write-on-ephemera proves small talk stays out of the knowledge base.

Reuse the knowledge-base pattern

Copy this shape when an agent needs durable, inspectable team knowledge:

• Resolve the storage root lazily behind an environment override.
• Validate identifiers in the store, not in the prompt.
• Put naming and structure conventions in a skill so writes stay consistent.
• Add a consolidation schedule instead of letting pages rot.

Where to go next

• Tools
• Skills
• Schedules
• Evals