A Knowledge Base Is Not a Search Box: Building Personal Wiki and Code Wiki in Open Nua

Open Nua Engineering

Many personal knowledge products begin with the same loop: put documents in, split and embed them, retrieve a few chunks, and ask a model to answer. That is useful for a prototype, but it leaves the long-lived questions unresolved. When a source changes, which conclusions should change? What did the model actually read? Can a generated refresh overwrite a page that a person edited? Should a research hypothesis, the current behavior of a codebase, and a durable fact about the user enter the same index with the same level of authority?

Open Nua did not turn its personal knowledge base into a larger search box. We built a local, profile-isolated knowledge workbench in which sources, standalone articles, Topics, Wiki pages, immutable revisions, citations, search, and build jobs have distinct responsibilities. Personal Wiki and Code Wiki share that foundation, but they use different source boundaries, structures, and quality standards.

The distinction is not branding. They are different cognitive jobs.

Four concepts that should not collapse into one

Personal Knowledge Core is the local system of record. It owns explicitly imported sources, standalone articles, Topics, pages, revisions, citations, build jobs, and deletion state. It also owns profile isolation, offline reading, search, and recovery.

Personal Wiki synthesizes material around a subject. It turns approved documents, research notes, and conversation artifacts that the user explicitly adds to a Topic into evolving themes, decisions, principles, and open questions.

Code Wiki is a cognitive map over approved repositories. It does not mirror the file tree. It helps a reader understand boundaries, call paths, ownership, architecture decisions, delivery history, and important entry points.

Long-term memory stores personal facts and events that an Agent may need in later turns: preferences, history, or current state. It has its own switch, tools, temporal semantics, and context budget. It is not a third Wiki and does not share the Wiki source of truth. Turning memory off does not delete a Personal Wiki; saving an article does not silently turn its content into a durable fact about the user.

Without these boundaries, “what the user wrote,” “what a model synthesized,” “how the code currently works,” and “what the Agent should remember” become one unauditable pool of text.

First principle: import is not inference

When a user selects a local document, directory, repository, or conversation artifact, Open Nua first performs a controlled import. It identifies the source, calculates a content digest, records a revision, and stores the result inside the current Desktop profile.

Import does not invoke a model, and it does not automatically create a Topic. Saving an article and asking AI to resynthesize a Wiki are separate user intentions. This gives the product three useful properties:

• Articles remain readable, editable, searchable, recoverable, and deletable without a model or network connection.
• A user can collect material before deciding which Topic, if any, should use it.
• Capturing a web article or conversation artifact cannot accidentally trigger an expensive, opaque rebuild.

Only an explicit Topic build or update confirms model authorization and creates a read-only snapshot for that job. The snapshot contains only approved, supported, budgeted content. Hidden files, secrets, binaries, dependency trees, build outputs, oversized files, symlinks, and path escapes are rejected before a model can see them.

The synthesis runtime sees an approved copy inside the Topic runtime, not the real repository. File reads and writes are constrained to a virtual root, and the process does not inherit host environment variables. The current implementation still exposes a shell rooted at the snapshot, while its Host contract forbids parent-directory and host-path access. It would therefore be inaccurate to call this an OS-level, shell-free sandbox. The Gateway performs only the model calls the user has authorized. Pages, revisions, and citations remain facts owned by Personal Knowledge Core on the Desktop.

One foundation, two different Wikis

Personal Wiki and Code Wiki both publish Markdown pages, internal links, and citations. Both support revisions, search, human editing, conflict handling, and offline reading. But they answer different questions.

Personal Wiki needs room for knowledge to grow into its own shape. An Agent-platform research Topic may develop sections for protocols, hosts, providers, clients, decision records, and a watchlist. A travel-research Topic needs none of those. The product offers goals such as sources, themes, decisions, and open questions, but it does not force every Personal Wiki to copy the same directory.

Code Wiki benefits from more stable cognitive entry points. Its default root navigation covers overview, repository map, runtime boundaries, modules, glossary, ownership, architecture decisions, issue-and-release history, and key source entry points. Those roots are not a page-count cap. A substantial subsystem, public entry point, or durable decision can receive a bounded child page, but the generator must not reproduce the source tree one file at a time.

The two products can therefore share storage and governance, but not one vague prompt followed by the hope that a model will infer the difference. Source types, structural constraints, page responsibilities, and quality gates must be explicit in the Topic contract.

A citation does not prove that the source was read

The first generation path had a subtle flaw. The model could access all approved sources, and the publication step associated those sources with generated pages. A page appeared to have citations, but the system could not prove which files the model had actually read.

Citation had become source membership rather than reading evidence. In a Personal Wiki, that could make an unread research note appear to support a conclusion. In a Code Wiki, attaching an entire repository to every page could hide real coverage gaps behind an impressive-looking source list.

The final design introduced an evidence ledger isolated by profile, Topic, and job. It records only the controlled sourceId, relative locator, snapshot content hash, tool type, time, and terminal state. It does not store source bodies, prompts, raw model output, absolute paths, or credentials.

Only actual reads and successful search hits can become page-level citation candidates. Directory listings and glob results prove discovery, not reading. During publication, the Core verifies snapshot identity, Topic, job, and content hash again. Unread, forged, stale, or cross-Topic citations fail closed.

This changes “the model says it used a source” into “the Host can verify which source in which immutable snapshot it read.” Only then does a citation become an auditable evidence chain. It is still page-to-file provenance rather than sentence-level entailment: the ledger proves that supporting material was read, not that every sentence in the synthesis is correct.

An even simpler failure occurred before the evidence chain. A large Code Wiki was once silently truncated at 500 files by an older snapshot budget. The generator was reasoning over an incomplete world without a reliable signal that anything was missing. The current snapshot defaults to 5,000 files, 2 MiB per file, and 64 MiB in total, and records eligible, included, and omitted coverage. If the budget omits any eligible file, the job now fails before the model call. An incomplete snapshot must be a visible build failure, not a successful-looking summary.

A well-formed Wiki can still be a bad Wiki

Renderable Markdown, valid links, and valid diagrams only prove that the artifact opens. They do not prove that it deserves trust.

Open Nua runs deterministic gates before publishing a candidate. They check page-level evidence, citation identity, unsupported claims, required source coverage, and the stability of unrelated pages. A large Code Wiki additionally checks whether critical boundaries such as the renderer, main process, Agent bridge, preload/shared contracts, persistence, IPC, Plugin and Capability integration, and test strategy are represented.

We deliberately did not ask a second model to provide a vague score for the first. The Host checks facts it can determine: whether a file exists, whether its hash matches, whether a page has real evidence, whether links resolve, and whether human revisions remain protected. Degradable quality problems can enter human review, but the reviewer must see the gap and record a reason. Authorization violations, forged provenance, and evidence-boundary failures cannot be bypassed by a review button.

This also changes what page count means. A Code Wiki is not better because it is longer, and file coverage is not a quality metric by itself. The goal is to let a reader form a correct mental model without reading the source. Another page is valuable only when a critical boundary, owner, or workflow would otherwise remain unclear.

Updating knowledge must protect human judgment

Every save creates an immutable revision. Generated pages, editorial changes, manual pages, and research decisions have different origins. A later update cannot treat all prior content as disposable model output.

When sources have not changed, a normal refresh returns an explainable no-op. It does not call a model or create a meaningless revision. When sources do change, the system computes added, changed, and deleted inputs plus affected pages before running an update over the existing Wiki. Human revisions require a three-way merge; conflicts preserve both sides and wait for the user.

Code Wiki also separates “apply a structural change” from “rebuild from scratch.” Adding one page can preserve the existing runtime and pages while generating only the new page and any necessary overview or direct dependency. A genuine full rebuild is a separate, explicit action.

That boundary came from an expensive failure. A change that only added a structural page triggered 2,261 model calls and 180.5M tokens across three builds. Page writing was incremental, but skeleton review, QA, and evidence repair still ran over the whole repository. We later bounded discovery, question generation, verification, and provenance reuse to a page impact set. A comparable real change moved from two failed runs totaling 2,055 calls and 159.1M tokens to a successful 383-call, 30.0M-token run. Incremental cannot describe only the pages written at the end; it must constrain the entire validation loop.

Personal Wiki updates emphasize epistemic state. New material may strengthen a conclusion, or it may make an older conclusion stale, superseded, or disputed. A system should not automatically replace an existing decision simply because a conflicting document was imported later.

Let the Agent use the Wiki without widening authority

A Wiki matters only when it can return to real work. After the current conversation explicitly receives Personal Knowledge access, the main Agent can search within its Topic allowlist and then read bounded content through a stable page and revision identity. Results include the Topic type, Wiki path, page role, and bounded provenance, so the Agent knows whether it is using a codebase summary or a personal thematic synthesis.

Those tools are not automatically inherited by general subagents. Personal long-term memory tools are not inherited either. Knowledge authority follows the current conversation allowlist; it does not expand merely because an Agent already has generic file tools.

Search remains local and deterministic today: Chinese phrase segmentation, bigrams, and bounded domain-concept expansion rather than an external embedding service. The goal is not to become a universal semantic search engine. It is to locate citable pages reliably without adding a network exit or a second indexing system of record.

Six conclusions from building the system

1. The core knowledge-base problem is ownership, not retrieval. Raw sources, generated pages, human revisions, citations, and memory need explicit owners, mutation rights, and deletion semantics.

2. Import, synthesis, and injection are three separate actions. Saving material should not invoke a model; generating a Wiki should not grant every conversation access; conversation authorization should not change source facts.

3. Personal Wiki and Code Wiki share infrastructure, not epistemology. One organizes themes, decisions, and uncertainty; the other organizes code boundaries, call paths, and ownership.

4. A citation is trustworthy only when it binds to an observed read. Belonging to the snapshot is not the same as being used. Discovery is not the same as reading.

5. Model output is a candidate, not a fact. Revisions, quality gates, conflicts, and human review decide whether it becomes published knowledge.

6. Long-term memory belongs outside the Wiki. A current fact about the user and thematic knowledge synthesized from user-approved material need different temporal semantics, switches, and failure handling.

Open Nua's personal knowledge system remains local, single-profile, and explicitly authorized. It does not scan the whole computer, enable external knowledge connectors by default, depend on a vector database, or promise cross-device synchronization.

It does something more foundational: preserve material as manageable sources, turn synthesis into a governed job, make pages revisioned projections, make citations verifiable evidence, and let Personal Wiki and Code Wiki answer the questions each is actually designed to answer.