Wiki Protocol

Portable agent protocol for building a persistent markdown wiki from raw sources, inspired by Andrej Karpathy's LLM Wiki gist.

Quick Start

Create a new wiki folder, install the protocol files, and create raw/:

curl -fsSL "https://raw.githubusercontent.com/BasalBit/wiki/main/install.sh" | sh -s -- my-wiki

Then:

1. Put source files in raw/.
2. Ask your agent to run initialize.
3. Ask your agent to run ingest.
4. Use query to ask questions against the compiled wiki.
5. Run lint periodically to keep the wiki healthy.

What This System Is

This system turns a folder of raw source files into a maintained, interlinked wiki. Instead of retrieving from raw documents from scratch on every question, the agent compiles those sources into persistent markdown pages under wiki/ and keeps them current over time.

The important idea is that the wiki compounds:

• sources get summarized into durable pages
• entities and concepts get updated as new evidence arrives
• useful query results can be written back automatically
• contradictions and open questions can be tracked explicitly

Core Idea

There are two layers you should care about:

• raw/ contains the source files you provide
• wiki/ contains the compiled knowledge base the agent maintains after initialize

Chat is not canonical. Important results only become part of the system when the agent writes them into the wiki.

Your Role

You do a small number of things:

• place source files into raw/
• ask the agent to initialize, ingest, query, or lint
• read the wiki outputs to understand the current state

You do not need to maintain the internal schema manually.

The Agent's Role

The agent does the maintenance work:

• creates the canonical wiki structure
• ingests and updates source summaries
• updates entity, concept, dispute, and query pages
• maintains indexes and logs
• preserves provenance and tracks uncertainty

One ingest or durable query may update many wiki pages. Multi-file changes are normal.

The Four Operations

initialize

Creates the canonical wiki/ structure and required files if they do not already exist.

ingest

Batch-compiles the current contents of raw/ into the wiki.

Important behavior:

• ingest scans all files currently present in raw/
• new files are ingested
• changed files are re-ingested in place
• unchanged files are skipped
• removed raw files do not automatically delete compiled wiki pages

Supported raw formats include at least:

• .txt
• .md
• .pdf
• .docx
• .doc

Legacy .doc is best-effort and may fail gracefully depending on the environment.

query

Answers questions against the compiled wiki first, escalating to source material only when needed.

Useful query results may be saved back into wiki/queries/ automatically, and important conclusions may also be folded into the main wiki pages.

lint

Checks wiki health, including structure, links, stale source state, missing citations, likely missing pages, and unresolved conflicts.

Example Prompts

Use prompts like these with your agent:

• Initialize this wiki using the AGENTS.md protocol.
• Ingest everything currently in raw/.
• Query the wiki: what are the main disagreements about this topic?
• Lint the wiki and fix straightforward issues.
• Ingest raw/ and then summarize what changed.
• Query the wiki for the current best answer, save the result if it is durable, and update any affected canonical pages.

Directory Overview

At a high level, the repository looks like this:

raw/
wiki/
  overview.md
  index.md
  log.md
  manifest.json
  sources/
  entities/
  concepts/
  disputes/
  queries/

What the main parts mean:

• raw/: source files you provide; treat this as your input area
• wiki/sources/: source summary pages
• wiki/entities/: pages about named things
• wiki/concepts/: pages about ideas, methods, or themes
• wiki/disputes/: material conflicts and important open questions
• wiki/queries/: saved durable analyses and answers

Main Files To Read

Start here when you want to inspect the wiki:

• wiki/overview.md: the current state of understanding
• wiki/index.md: where pages live and what exists
• wiki/log.md: what changed over time

You can also browse:

• wiki/disputes/ for unresolved conflicts and open questions
• wiki/queries/ for saved analyses and durable answers

What Happens During Ingest

When you ask the agent to ingest:

1. it reads the current wiki state
2. it scans all files in raw/
3. it compares current files against prior ingest state
4. it creates or updates source pages
5. it updates affected concept, entity, dispute, and index pages
6. it logs what changed
7. it runs lint

This means one ingest run can touch many files. That is expected.

What To Avoid Editing Manually

Use the system through the agent.

Manual editing is discouraged, especially for:

• wiki/manifest.json
• wiki/log.md
• wiki/index.md
• folder-local indexes
• schema-heavy wiki pages that the agent is maintaining structurally

You should manage raw/ yourself by adding, updating, or removing source files there. The agent should read from raw/, not maintain it for you.

High-Level Structure Notes

You only need a high-level mental model:

• raw/ is the source layer
• wiki/ is the compiled knowledge layer
• the agent maintains the wiki according to AGENTS.md
• chat is not memory; the wiki is memory

If something important should persist, ask the agent to write it into the wiki.