The Wiki That Remembers Why

OpenWiki is a command-line system that asks an agent to read a repository or a set of personal sources, then turns what it finds into a Markdown wiki. The important question is not whether a model can produce readable pages once. It is whether those pages can remain useful when the underlying source changes: can a later run tell which facts need attention, preserve work that is still correct, and leave readers with a navigable artifact rather than a pile of stale notes? Understanding how OpenWiki answers that question gives us a way to judge both its engineering choices and its limits.

The failure is not an empty page

A one-time documentation generator can look successful while it is still failing at the job people actually need. It may describe a codebase accurately on Monday, but a refactor on Tuesday can make several explanations wrong. The problem is not limited to the paragraph that mentioned a renamed function. Page relationships may no longer reflect the system, indexes may point to the wrong concepts, and a citation may say only “the repository” without showing which source supported a particular statement. When the next run starts, it needs more than a prompt to “update the docs.” It needs a way to distinguish a fact that remains current from one that must be reconsidered.

Consider a page that explains how a repository's components coordinate. A source change may leave most of the explanation intact while changing one responsibility, one failure path, or one assumption about persistence. Treating the page as a single undifferentiated text blob creates two bad choices: regenerate everything and risk unnecessary churn, or preserve everything and risk carrying a false statement forward. The useful unit of maintenance is smaller than the page, but richer than a raw line number. It is a meaningful proposition connected to the evidence that makes it true.

That distinction changes the design. Documentation becomes a maintained knowledge artifact with at least four responsibilities:

  • It must preserve a useful explanation for people and for coding agents that consume the wiki as memory.
  • It must connect material factual statements to evidence that can be checked again.
  • It must make partial progress safe, so an interrupted model does not leave behind a page that appears finished but has lost its prior grounding.
  • It must keep navigation and machine-readable metadata consistent after the model has written its prose.

These responsibilities also pull in different directions. A system optimized only for readable prose may hide its uncertainty. A system optimized only for traceability may produce a database of citations that no one wants to read. A system optimized only for automation may overwrite a carefully maintained page whenever a model sees the repository differently. OpenWiki's architecture is interesting because it separates these concerns instead of asking one model response to solve them all at once.

OpenWiki is built around those responsibilities. The model remains important—it researches and explains—but it is not the sole owner of continuity. A durable page lifecycle, versioned Claims, deterministic finalization, and constrained tool access surround the model's work.

One product, two choices

OpenWiki's scope is easiest to understand through two independent choices. The first is the mode: what kind of knowledge is being documented and where the result lives.

In code mode, the subject is the current Git repository. The wiki is written into openwiki/ inside that repository, so the documentation can travel with the source it describes. This is the mode with repository-grounded Claims: factual propositions can point to versioned evidence in the checkout, and later updates can ask whether that evidence is still current. The generated wiki is therefore part of the repository's working context, not just an export sent elsewhere.

In personal mode, the subject is a person's connected knowledge sources. The wiki is stored under the OpenWiki home directory, ~/.openwiki/wiki by default, though OPENWIKI_CONFIG_DIR can select another state directory. This mode can ingest sources such as messages, search results, local repositories, or MCP-backed services. Those observations can be synthesized with confidence labels and contested sections, but they do not receive the same repository-evidence Claim guarantee as code-mode pages. A fact retrieved from an external service has a different freshness and provenance problem from a fact read directly from the repository being documented.

That difference is not a minor configuration detail. In code mode, the system can re-resolve a repository resource and compare it with the version captured for a Claim. In personal ingestion, a connector may return a new message, a search result, or a provider-specific view of the world; the system can preserve raw material and signal confidence, but it cannot treat all such material as a stable, locally verifiable source in the same way. Keeping the guarantees separate is more honest than giving every output the same “grounded” label.

The second choice is the driver: who supplies the model and repository tools. In native generation, OpenWiki resolves a configured provider and runs its own planner and page workers. In host-driven generation, a supported coding agent—Codex, Claude Code, OpenCode, or Cursor—uses its own authenticated model and native repository tools. OpenWiki still owns the durable page-job lifecycle, Claim validation, and finalization. Host-driven execution therefore changes the authoring boundary, not the meaning of a completed page.

The distinction is not an automatic quality ranking. Native execution gives OpenWiki direct control over its model setup and worker loop. Host-driven execution can give a coding agent better access to an existing session, tools, or credentials. In both cases, the important question is which side owns the irreversible effects. The authoring agent can investigate and write its assigned Markdown, while OpenWiki controls the state transitions and the machine-maintained records that say what was accepted.

These choices matter because they prevent a tempting but unsafe simplification: treating every OpenWiki run as the same kind of “AI documentation.” The input, state location, credentials, grounding rules, and failure behavior depend on the path being used.

flowchart LR Code["Code repository"] --> Mode["Code or personal mode"] Personal["Connected personal sources"] --> Mode Native["Native OpenWiki model"] --> Author["Agent research and prose"] Host["Host coding agent"] --> Author Mode --> Author Author --> Jobs["Durable page jobs"] Jobs --> Claims["Claims and evidence"] Claims --> Final["Deterministic finalization"] Final --> Humans["Human-readable wiki"] Final --> Agents["Agent memory"] Humans --> Changes["Source changes"] Agents --> Changes Changes --> Jobs

The diagram is deliberately a loop rather than a straight pipeline. A page is not the end of the process. Once the repository or source set changes, the artifact becomes an input to another maintenance pass.

From source to maintained knowledge

The code-mode path gives that loop a concrete shape. OpenWiki first establishes a run and a planning context. A planner proposes the pages that should exist and the work each page requires. The system then normalizes that proposal into an ordered queue of page jobs. Each job has a page path, a purpose, relevant starting points, related pages, and instructions. The queue is not just a convenient task list: it is the durable unit of work that lets the system know what has been completed and what remains.

That normalization is important because a model's plan is flexible while a recovery system needs stable boundaries. OpenWiki canonicalizes page paths, rejects conflicts between generated and deleted pages, and adds work that the planner cannot legitimately omit, such as a page with unresolved evidence debt. The navigation-oriented quickstart page is placed after domain pages so it can describe the structure that actually exists. These are small rules, but together they turn a conversational proposal into an ordered set of responsibilities.

The run state makes the queue survive beyond one process. An in-progress run is recorded in openwiki/.run.json, with its phase, source identity, planning context, and page progress. Writes are made atomically, and the in-memory state advances only after the durable checkpoint succeeds. If the model stops after several pages, the next run can reconstruct the unfinished work instead of treating the whole generation as either complete or lost.

That recovery has a deliberate limit. OpenWiki fingerprints the model-visible repository source used by the plan. If the source changes while a plan is in progress, resuming the old plan would mix two different versions of the repository. The plan is therefore invalidated and planning starts again. If source changes are detected during finalization, OpenWiki still finishes the deterministic work but records an interrupted update and tells the operator to run another update. It does not quietly claim that a moving source was fully covered.

A page worker researches only its assigned page, writes the Markdown, and submits the page. Around that activity, OpenWiki can keep the page's factual Claims separate from its prose. A Claim is an atomic proposition about the system, such as a responsibility, relationship, lifecycle rule, or failure behavior that materially affects how a reader understands or changes the repository. Its evidence identifies repository material and includes a resolver-owned version. The page can therefore retain a clean reading surface while the system keeps a more precise record of why the page is trusted.

The update decision then becomes more meaningful than “the last run was a while ago.” OpenWiki rechecks persisted evidence. If a referenced file has changed, the Claim is stale; if the file or selected evidence can no longer be resolved, the Claim is unresolved. A clean Git status does not override those findings. The page must return to the work queue so the agent can confirm that the proposition still holds, revise it against current code, or remove it. Conversely, a current Claim does not need to be copied through every model turn merely to prove that it was not forgotten.

The last part of the loop is also intentionally divided. The agent authors the explanation, but deterministic code performs the work that should not depend on a model's mood or formatting habits. OpenWiki validates and repairs the required OKF front matter, synchronizes directory indexes, checks internal links, projects Claim evidence into machine-readable sources, and reconciles generated provenance. Mermaid diagrams are parsed when the optional authoritative dependencies are available; if a diagram is clearly invalid, the system can convert it to readable text with a repair comment rather than leave a broken block for the next renderer.

The resulting artifact serves two readers at once. A coding agent can use the Markdown as compact repository memory, while a human can follow links, indexes, and the visualizer's graph to understand relationships among pages. The graph does not create new truth; it exposes the relationships already expressed by Markdown links. That distinction matters. Navigation can make a knowledge artifact easier to inspect, but only the evidence and the page's explanation can support a factual conclusion.

This division clarifies what “self-maintaining” can reasonably mean. It does not mean that OpenWiki independently discovers every important idea or guarantees that an agent's explanation is insightful. It means that the system makes the relationship among prose, evidence, state, and change explicit enough to maintain. Code can verify that a page's Markdown bytes match its Claim sidecar, that a source version has changed, or that a generated index is consistent. It cannot prove that the agent noticed a material concept that no Claim represents.

The practical judgment

The most useful way to approach OpenWiki, then, is not as a replacement for documentation judgment. It is as an architecture for making that judgment persistent. The product's central subject is the wiki it builds and maintains; evidence-backed maintenance is the lens that explains why its queue, Claims, finalizer, integrations, and visualizer belong together.

That lens also sets the standard for evaluating the system. A generated page is valuable when a reader can understand the repository, an agent can use the page as context, and a later update can identify what deserves another look. A durable wiki must preserve continuity without hiding uncertainty, expose relationships without pretending they are evidence, and recover from interruption without promoting partial work to a finished result.

OpenWiki's opening promise is therefore modest but technically demanding: make documentation a living relationship between explanation and source. The next question is how that relationship becomes recoverable work in practice—how a repository is converted into an ordered page queue, and what OpenWiki is willing to mark complete when an agent stops halfway through.

References