The wiki

What this is

The wiki is Ouroboros’s curated layer of markdown pages: plain .md files with YAML frontmatter at ~/Ouroboros/vault/wiki/<type>/<slug>.md, indexed in the encrypted database for fast lookup but not owned by it — delete the index and the files re-index from disk on the next scan. Every page has a type from a fixed six-value enum — concept, entity, source, decision, architecture, comparison — and the files are ordinary enough that opening the vault folder directly in Obsidian, or grep-ing it from a terminal, just works.

Why it exists

An agent doing real synthesis work — “here’s what I concluded about this entity,” “here’s the decision and its rationale” — needs somewhere durable to put that conclusion that isn’t a raw document (which it didn’t author) and isn’t sophia.remember_fact (which is for short, atomic claims, not a written-out argument). The wiki is that surface, and Chris’s product ruling on the 2026-07-07 wiki-reshape arc made it a default rather than something an agent has to think to create: “every entity basically should have an attached wiki… we should create the wiki for them, but also allow them to add their own wikis as ‘add-ons’ if required.” The same ruling drew the boundary that gives this page its shape — user wikis may not follow the same conventions, and nothing forces them to: the canonical layer is system-curated, an attached add-on stays exactly as its owner wrote it.

How it works

Canonical seeding. seedCanonicalWiki() (proxy/src/wiki/seedCanonicalWiki.ts) is called from both entity-creation paths — POST /api/entities and the MCP sophia.create_entity tool — so every new entity gets one type: 'entity' home page the moment it exists, written through the same pageManager the MCP wiki tools use (no parallel write path). The slug is deterministic — <slugified-entity-name>-<short-id>/home — and existence is checked by entity_id plus frontmatter.source === 'canonical', not by slug, so renaming the entity later never spawns a duplicate home page. A one-time backfill (backfillCanonicalWikis) seeded this for entities that pre-date the feature, filtered to trust_tier = 'curated' AND type NOT IN ('agent', 'wiki') — a Chris-reviewed gate decision that excluded 15 agent-key entities and 6 legacy wiki-of-a-wiki entities, landing on 12 real-world entities actually seeded. The old POST /api/wiki/bootstrap route, which used to create a separate type: 'wiki' entity for this, is retired (410, with a pointer comment) now that seeding happens on the entity itself.

Attached vaults are add-ons, not imports. An owner can attach an existing folder — an Obsidian vault, a docs wiki — to an entity as a wiki_addon docs root (subscriber_entity_docs_roots.root_kind = 'wiki_addon', in proxy/src/extraction/docsRootManager.ts). That folder flows through the same ingest pipeline as any other docs root: its files land in subscriber_document_artifacts with source_type = 'docs_root_scan'. They are never written through writeWikiPage and never appear in subscriber_wiki_page_index — the isolation isn’t a convention an agent is asked to respect, it’s structural: there is no code path that promotes an add-on file into a canonical row. sophia.list_wiki_pages surfaces both sets on request but keeps them in separate arrays, each add-on entry tagged source: 'addon' plus its root path. (A different, older tool, sophia.register_vault_folder, does something else entirely — it classifies an external vault’s files by folder and imports them in place as real canonical pages; it’s a one-time migration path, not an add-on attachment, and the two aren’t interchangeable.)

flowchart LR
  E["Entity created"] -->|seedCanonicalWiki| C[("subscriber_wiki_page_index<br/>canonical pages")]
  A["sophia.write_wiki_page /<br/>update_wiki_page"] --> C
  V["Owner attaches a vault folder<br/>(root_kind='wiki_addon')"] -->|docs ingest pipeline| D[("subscriber_document_artifacts<br/>source_type='docs_root_scan'")]
  C --> L["sophia.list_wiki_pages<br/>(pages[])"]
  D -.include_addons:true.-> L2["sophia.list_wiki_pages<br/>(addon_pages[], source:'addon')"]

What your agent does with it

The calls below are real, captured against this daemon on 2026-07-09.

const idx = await sophia.list_wiki_pages({ include_addons: true, limit: 10 });
// → { total: 10, addon_total: 0, addon_pages: [],
//   items: [
//     { slug: 'joan-keller-trust-97624a8b/home', type: 'entity',
//       title: 'Joan Keller Trust', body_chars: 204, valid_from: '2026-07-07T02:01:00.912Z' },
//     { slug: 'llm-workspace-research-implications', type: 'concept',
//       title: 'LLM Internal Workspace ("J-Space") Research…', body_chars: 7844 },
//     // ...
//   ] }

const page = await sophia.read_wiki_page({ slug: 'joan-keller-trust-97624a8b/home' });
// → { type: 'entity', title: 'Joan Keller Trust',
//   frontmatter: { about_entity: '97624a8b-...', source: 'canonical', created: '2026-07-07' },
//   author: 'system-backfill',
//   absolute_path: '~/Ouroboros/vault/wiki/entity/joan-keller-trust-97624a8b/home.md',
//   signature_status: 'valid', body_chars: 204 }

That second call is a real canonical home page seeded by the backfill run: short, honest starter content (“Build it out as you learn more”), no placeholder filler, frontmatter.source: 'canonical' marking it as system-seeded rather than hand-authored, and signature_status: 'valid' confirming the file on disk hasn’t drifted from what the daemon signed. This particular daemon has zero add-on vaults attached right now, hence addon_total: 0 — the field exists in every list_wiki_pages response whether or not anything is attached.

An agent writing its own synthesis calls sophia.write_wiki_page({ slug, type, title, body, sources?, related?, source_freshness? }) — type must be one of the six enum values above, and the call fails with slug_collision if the slug is taken (sophia.update_wiki_page revises an existing page instead, via bitemporal supersession). sophia .list_pages_by_tag({ tag }) rounds out discovery — it queries the same Obsidian-style tag index (#tag in the body or tags: in frontmatter) that gets refreshed on every write, so a tag-scoped index never drifts from what’s on disk.

Boundaries

Add-ons are read-through: sophia.fetch_document(artifact_id) reads their content, sophia.read_wiki_page has no entry for them, and no write tool in this surface ever promotes a source: 'addon' file into the canonical index. That boundary belongs to this page and to Mining, whose ingest pipeline is what actually pulls add-on file bytes in — the wiki layer only claims the read-side tagging.

Wiki pages are also, structurally, documents: sophia.search_documents hybrid-fuses BM25, dense, and graph signal over all document content including wiki bodies, so a query for something you wrote up last week can surface a wiki page next to a mined source in the same result list — how that ranking actually works is Search & Retrieval. And the canonical wiki is not a general notes app: it’s the graph’s curated layer, seeded per entity and grounded in the same mutation journal, supersession chain, and citation-verification machinery as everything else Sophia writes — the entity rows a canonical page hangs off of are Knowledge Graph’s territory, and the provenance model behind [^fact:id] / [^artifact:id] citations is Truth. What the daemon and its storage layers look like end to end is The State Layer.