Maintaining an AI-assisted knowledge base with clear boundaries

What a knowledge base needs to preserve

AI can help summarize and connect notes. It can also overwrite earlier facts, lose sources, mix assumptions into self-descriptions, or resolve contradictions too quickly.

These are risks to manage, not an inevitable outcome. The two Skills organize source tracking, write permissions, and verification into a workflow that helps the owner review changes.

Two Skills: initialize and maintain

The toolkit splits into two Skills that work together:

co-evolution-wiki answers to /wiki and runs once per vault. It materializes an empty second-brain skeleton — the full directory tree, five entry channels, system rules, retrieval scripts, and page templates.
wiki-up answers to /wiki up and runs every time the owner asks for an incremental update. It scans, ranks, promotes, rebuilds the index, verifies, and reports.

Both enforce the same hard boundaries: sources are read-only, no encrypted-chat parsing, no sensitive-value extraction, no self-narrative auto-editing, and no scheduled automation of any kind. Updates are owner-triggered only. There is no cron, no daemon, and no “sync at midnight.”

Three layers: fact, self, and structure cannot leak into each other

The foundational decision is that a knowledge base cannot be a single layer. Mix project output, the user’s self-description, and the wiki’s own change history together, and the AI gains a channel to infer personality from project results — building VR projects does not mean “loves immersive experiences,” and that inference has to be physically blocked.

So the architecture partitions the vault into three layers:

Fact layer: observable, sourceable, falsifiable. Projects, technologies, people, timeline, decisions. Every claim must trace to a file:/// link.
Self-narrative layer: only what the owner has explicitly said — values, beliefs, principles, decision style. Written only through the main-self-up interview channel, with a snapshot in evolution/ before any write.
Structural evolution layer: the wiki’s own change history. Directory renames, page merges, schema migrations, self-narrative snapshots all land here.

There is no AI-built bridge between the layers. The fact layer cannot infer the self layer. The self layer cannot rewrite facts. Conflicts go to self/thoughts/contradictions and wait for the owner to clarify — they are never auto-resolved.

Five channels: every operation writes to its own surface

“Ask a question” and “update the whole vault” should not have the same write permission. The architecture gives each operation its own entry channel:

main-self: query, read-only, writes nothing.
main-self-update: global fact-layer deep-dive, writes entity pages and indexes.
main-self-empty: current-task sediment, writes only pages touched by this task.
main-self-up: self-narrative interview and evolution, writes self/thoughts/*. Red zone.
periodic-maintenance: full-vault maintenance after the owner types wiki up. Runs the wiki-up Skill’s seven-step workflow.

Channels are operation modes, not knowledge bodies. The knowledge still lives in the three layers. The benefit: a “quick question” cannot accidentally rewrite the vault, because it never reaches a channel that can write.

Seven judgment types: classify before you touch a page

During an update, the scanner returns a pile of candidates — new files, changed READMEs, a person directory that just appeared. Before any of them touches a page, each one is classified into one of seven types:

create: a brand-new entity. Create a page.
update: new facts for an existing entity. Append, do not overwrite.
link: only a new relationship. Update wikilinks on both sides, leave entity facts alone.
merge: two pages describe the same entity. Record the rationale in evolution/ before merging.
archive: outdated. Mark archived, do not delete the source facts.
ignore: matches ignore rules or is unrelated. Skip.
conflict: two sources contradict. Goes to inbox with both links. Do not pick a winner.

The seventh type is the important one. The most common AI failure is seeing two contradictory sources, picking the one that “looks more correct,” and deleting the other. This architecture treats contradiction as information to preserve, not as noise to eliminate immediately.

Three-zone write boundary: auto-write, confirm, approve

Classification is not enough. The write itself passes through a risk tier:

🟢 Safe Zone auto-writes: sync-log, briefs, ephemeral context, fact-layer appends, index updates. Low risk, reversible, does not touch identity.
🟡 Review Zone confirm-then-write: new entity pages, wikilink relationship changes, inbox → new page, structural renames and merges. Medium risk, affects the knowledge graph.
🔴 Approval Zone explicit approval only: any self/thoughts/* write, the owner’s “who am I” section, core principles, evolution snapshots. High risk, directly affects who the owner is. The AI never writes here without explicit approval in the current run.

Regardless of zone, a few things are absolutely forbidden: no personality inference from project output, no value inference from chat snippets, no flattery, no disparagement, no psychological diagnosis. These are not suggestions. They are hard boundaries.

Inbox: uncertain things do not enter the fact layer

If a candidate fact cannot satisfy all six automatic-promotion conditions — explicit readable source path, unique entity mapping, no unresolved conflict, observable and not identity-inferring, no sensitive value, affected page and indexes updateable together — it does not enter any canonical page. It goes to _system/inbox.md with the source link, the failing condition, and a suggested resolution path.

The inbox is the escape valve. Conflicts, sensitive values, self-narrative inference attempts, filename-only evidence, possibly-stale state — all route here instead of into a canonical page. The AI never resolves inbox items on its own.

L0–L3 tiered retrieval: answer from the cheapest sufficient layer

Answering a question does not mean spreading the entire vault of raw files across the context window. Retrieval walks in layers:

L0 routing: use INDEX and classification indexes to scope the topic.
L1 canonical: answer from authoritative entity pages — projects, technologies, people, domains.
L2 context: read timeline, decisions, and supporting pages only when history or cause is needed.
L3 evidence: read source pages or open file:/// links only when evidence is insufficient or the user asks for sources.

Answers come from the cheapest sufficient layer. Context windows stay lean. A user asking “what is project X” does not get a screenful of source code.

Verification contract: do not promote bad data, ever

The last step of wiki up is not “done.” It is verify. Valid Markdown frontmatter, unique IDs, resolvable wikilinks, openable file:/// links, no privacy violation, source coverage for new facts, a same-generation retrieval database and manifest, passing golden-query thresholds. If any check fails, every page changed in this run is restored from backup and the previous known-good retrieval pair is retained.

The retrieval database and manifest are disposable caches. Markdown is the only source of truth. A broken cache does not corrupt facts; it only degrades search.

Try it with two commands

Initialize a new vault:

python skills/co-evolution-wiki/scripts/init_wiki.py \
  --owner "Your Name" --vault "/path/to/wiki"

Then every update is one line:

wiki up

Full installation, architecture, and verification contracts are in the siyan-brain-skills repository.

Closing thought

The hard part of letting an AI maintain a knowledge base is not making it write more cleverly. It is making it stop where it should. The three-layer model blocks identity inference. The seven judgment types preserve contradiction instead of eliminating it. The three-zone write boundary leaves high-risk writes to human approval. The inbox catches everything uncertain. These rules support long-term maintenance. Their effect still depends on source quality, human review, and how faithfully the workflow is followed.