Skip to content

Wiki ​

The wiki is the long-term knowledge all your agents share. It is a folder of Markdown pages inside your Obsidian vault: one page per person, project, device or rule. somora writes it from the agents' notes, and you can read and edit it like any other note.

What you get ​

  • One shared picture. A fact one agent learned is known to all of them, on one page per thing.
  • Curated, not collected. The Deep phase turns loose notes into pages and removes the notes. One source of truth per topic.
  • Yours to edit. Pages are plain Markdown in your vault. somora never overwrites a page you changed while it was working on it.
  • A tidy structure. A folder says what kind of page lives in it, so a thousand pages still fit a dozen folders.
  • A browser with a graph. The web client shows the pages, their links and what links back.

Set it up ​

The wiki is off by default. It needs a vault and a subfolder name:

yaml
# ~/.somora/config.yaml
obsidian:
  vault: ~/Documents/Vault
wiki:
  enabled: true
  vaultSubfolder: somora      # <vault>/somora/ becomes the wiki
  language: en                # de (default) | en
  deep:
    model: <model>            # worker model for Deep
  lucid:
    model: <model>            # worker model for Lucid

You do not need Obsidian itself. obsidian.vault can be any folder of Markdown files. Without it there is no wiki.

Restart the server. Deep fills the wiki from the agents' notes on its next run, or at once when an agent calls dream_run({phase: 'deep'}).

Where it lives ​

<vault>/
├── … your own notes (read as source "vault", never written) …
└── <wiki-subfolder>/
    ├── index.md               ← list of all pages, regenerated by Deep
    ├── _structure.md          ← the folders and what lives in them
    ├── people/
    │   └── nina-muster.md
    ├── projects/
    │   └── house-build.md
    ├── knowledge/, places/, … ← see "Folders: kind, not topic"
    └── logs/
        └── YYYY-MM.md         ← monthly change log

This is the English set. With language: de the names are German: personen/, projekte/, wissen/, orte/, _struktur.md.

Each agent also has a private memory inbox under ~/.somora/agents/<name>/memory/. The inbox is short-term and belongs to one agent. The wiki is long-term and shared.

Who writes the wiki ​

WriterWhenWhat it does
Deepevery 12 hours, or dream_run({phase: 'deep'})Reads each agent's inbox. Per note it skips, creates a page, or merges into a page. A used note is deleted. No approval step.
Lucidevery 7 days, or dream_run({phase: 'lucid'})Checks the wiki for contradictions, dead links, missing, duplicate, misfiled and oversized pages. Sets plain link suggestions itself. Everything else waits for review.
An agent in reviewwhen you start dream_reviewWalks the Lucid findings with you and changes pages with wiki_edit, wiki_create, wiki_delete and wiki_move after you agree to each step.
Youany timeEdit a page in Obsidian and save.

The four wiki_* tools only work for the agent that holds a dream_review loop. An agent that dreams can also edit wiki files with file_write and file_patch outside a loop; one with dreams: false cannot.

Every write checks the file's modification time first. If you changed a page after somora read it, the write is dropped and tried again on the next run. Your edit is picked up by the file watcher and indexed once, for all agents.

Two guards protect large pages. A merge that would shrink a page to less than half is refused (wiki.deep.mergeShrinkGuard). A page over 50,000 characters takes no more content: Deep files the note as a sub-page under it (wiki.deep.maxPageChars).

Page format ​

markdown
---
slug: people/nina-muster
type: person
created: 2026-05-08
updated: 2026-05-09
sources:
  - ada/nina-muster
  - bea/people
related:
  - places/main-house
---

# Nina Muster

## Current state

Nina is Karl's sister and lives in the main house …

## Properties

- **Brother:** Karl Muster

## Timeline

- 2026-05-08: moved into the main house

## Notes

- See also [[places/main-house]]
FieldRequiredMeaning
slugyesPath inside the wiki without .md. Matches the file's location.
typeyesLoose category. Deep prefers person, project, concept, place, tool (de: person, projekt, konzept, ort, werkzeug) and may use others.
createdyesDate the page was created.
updatedyesDate of the last change. Refreshed on every write.
sourcesno<agent>/<memory-slug> entries: which inboxes contributed.
relatednoOther wiki pages, as paths without .md.

New pages get four sections. You can add others: a merge keeps the structure a page already has.

endeContent
## Current state## Aktueller Standa short summary in prose
## Properties## Eigenschaftenstable facts as a list
## Timeline## Zeitleistedated entries
## Notes## Notizeneverything else, cross-references

Link pages with Obsidian's [[path]] or [[path|label]]. Search does not follow links. An agent that sees a link in a hit decides itself whether to read that page with memory_get.

Folders: kind, not topic ​

A folder says what kind of page lives in it: a person, a project, a device, a rule. It never says what a page is about. Topics live in the page text, in links and in index.md. Without this rule a wiki grows a folder per topic and the same page name in several of them.

somora ships one folder template per language. Your wiki's real folders win: a folder you or Deep created is used as it is, and the template only fills gaps. Subfolders go one level deep at most.

endeWhat lives there
people/personen/one page per human
companies/unternehmen/one page per company, firm, supplier
projects/projekte/one page per bounded undertaking. Dated work reports are timeline entries on it, not pages.
infrastructure/infrastruktur/subfolders devices, hosts, services, accounts (geraete, hosts, dienste, konten)
finances/finanzen/subfolders accounts, portfolio, crypto, real-estate, loans (konten, depot, krypto, immobilien, kredite)
possessions/besitz/things owned that are not investments
places/orte/houses, sites, cities, destinations
events/ereignisse/what happened when
knowledge/wissen/knowledge tied to no person or company. Subfolders concepts, how-tos, comparisons (konzepte, anleitungen, vergleiche)
rules/regeln/directives, preferences, agreements
agents/agenten/agent profiles only, no work reports
personal/privat/interests, hobbies, pets, health, living

The structure file ​

_structure.md (_struktur.md with de) in the wiki root holds one table row per folder: its purpose, who described it (template, deep or user) and since when. Deep writes it after a run that created a folder or met an undescribed one.

Edit the sentences in Obsidian like any page. Your wording and the template's are never overwritten. The file is not a wiki page: the index and the search skip it.

How Deep files a page ​

On every run Deep sees a map of the wiki: every existing folder with its purpose and page count, the template folders that do not exist yet, and the rules. Then:

  • A new page goes into a described folder. A folder nobody has described shows as "(no description yet)" and is not used until someone describes it.
  • A new folder needs a purpose. Deep may create one only when no kind fits, with one sentence on what lives there. The sentence goes into the structure file. A folder without a purpose, or deeper than one subfolder, is refused and the note waits for the next run.
  • No twins. The page name is checked against the whole wiki. If a page of that name exists in another folder, Deep merges into it. Names that already exist in several folders are listed in the structure file.
  • Details go to their entity. A note named acme-capital-reserve while companies/acme exists is usually a detail of acme. Deep is asked again with that page in full and merges, unless it insists the note is a thing of its own.

The index page ​

Deep regenerates index.md after every run. It has one section per top folder, one line per page with a short description, and the last 10 changes of that run. Pages in the wiki root are listed under Other (Sonstiges).

markdown
# somora wiki index

Last update: 2026-05-09 07:45 UTC by Deep

## People
- [[people/nina-muster]] — Karl's sister, lives in the main house …

## Projects
- [[projects/house-build]] — Extension of the main house …

## Recent updates
- 2026-05-09: [[people/nina-muster]] — nina-muster updated: address

The description is the page's description field if it has one, otherwise its first line of prose, cut at 120 characters.

How agents read the wiki ​

WayWhat the agent gets
Automatic recallWiki sections that fit the message, in the <memory-context> block, tagged [wiki/<path> · score=N.NN]. A wiki hit counts 1.4 times its score, so curated pages rank ahead of raw notes.
Overview blockA map of what the wiki holds, in the system prompt.
Toolsmemory_search to search, memory_get('wiki/<path>') to read a whole page, memory_list with source: "wiki" to browse a folder.

A reference is wiki/ plus the slug: wiki/people/nina-muster.

Overview block ​

The overview tells the agent which topics the wiki holds, so it knows what is worth searching for. It carries page names only. Content comes from recall and memory_get.

It sits in the system prompt and is frozen for the session: it is built on the session's first turn and stays the same after that. A block in front of the whole conversation must not change, or the provider's prompt cache is lost on every Deep run.

Recall is not frozen. Search always uses the live index. To get a fresh map, start a new session or /reset the current one.

index.md rarely fits the budget of wiki.search.overviewMaxChars. somora then shortens it in stages. Every stage covers the whole wiki:

StageContentUsed when
1index.md as it isit fits the budget
2sections, pages, descriptions cut to 100 characterssmall wiki
3sections and bare page linksmedium wiki
4section names with page countslarge wiki

Stage 4 says - Projects (60) and does not list some of the pages. A partial list looks complete and stops the agent from searching. With the default of 4000 characters, page names stay visible up to roughly 120 pages.

Tip

Raise overviewMaxChars to keep page names visible on a larger wiki. The cost is a bigger system prompt, paid once per session.

Language ​

wiki.language sets what the wiki's scaffolding is called and which language Deep writes in:

  • the section headings and type values of new pages
  • the folder template and the name of the structure file
  • the wording of index.md and of the monthly log
  • the examples in the Deep and Lucid prompts
  • the language of titles, headings and prose that Deep writes

de is the default. Switching later changes new scaffolding only. Existing pages are not translated, and a merge keeps the headings a page has. Names and terms are quoted as they appear in the note, whatever the language. Notes and search are not affected.

Web explorer ​

The web client has a read-only wiki window behind the wiki tile in the dock. The tile appears when the wiki is enabled. It carries a badge while Lucid findings wait for review.

ColumnWhat it shows
TreeFolders and pages, a filter box, a re-scan button and the page count.
PageThe rendered page. [[links]] open inside the window.
GraphThe link graph, then the page's backlinks and its broken links.

A link that matches no page is shown as broken. Links resolve like in Obsidian: exact path, then path ignoring case, then a page name that is unique in the wiki. A name that fits several pages stays unresolved.

The graph has two views. This page shows the page, what it links to, what links to it and the links among those. Whole wiki shows all pages, limited to the 400 best connected. related entries count as links. index.md is left out because it links to everything.

Scroll to zoom, drag to pan, click a node to open the page. The expand button gives the graph the whole window.

Edits made in Obsidian show up within about 10 seconds. The re-scan button skips the wait. There is no editor on purpose: an editor in the browser would race Deep and Lucid.

Migrating a grown wiki ​

A wiki that grew without the template keeps working. The map only decides where new pages go. Moving existing pages onto the template is a separate process that only you start. You approve it in groups, and it copies the whole wiki before it moves a file.

Run somora wiki migrate on the somora host. It walks you through four steps. Each step is also a subcommand and a route, so a script or an agent can drive it. See Commands and Routes.

Warning

A real run needs the words "move my wiki" from you. An agent may plan, judge, read the groups to you and record your approvals. It must not supply those words on its own.

  1. Plan. Reads the wiki and writes plan.md: folders a rule would move (a folder named stocks belongs in finances/portfolio), page names that exist in several folders, and dated work reports with the project they seem to belong to. Nothing is touched.
  2. Judge. The Lucid model looks at every page and answers: keep, move, fold into an existing page, or unclear. No page moves on a folder name alone. The answers land in refined.md, grouped by what would happen: "move 12 pages to infrastructure/devices". Nothing is touched.
  3. Approve. You approve or dismiss groups, all groups of one action, or the unions of same-name pages. What you do not approve stays where it is.
  4. Execute. The default is a dry run that writes dry-run.md and nothing else. The real run does the steps below.

A real run, in this order:

StepWhat happens
BackupA full copy of the wiki, checked by file count. No copy, no run.
MovesThe file moves and its slug follows.
FoldsThe model writes the page's substance into the target: a timeline line for a dated report, a few lines under the fitting heading for a detail. The original is kept in logs/reports/ (logs/berichte/) with merged_into in its frontmatter. This archive is not searched.
UnionsOf two same-name pages one survives with a merged text. The other goes to the same archive.
LinksEvery [[link]] and related entry is pointed at the new places.
CleanupEmpty folders are removed. The structure file, index.md and the monthly log are updated. The search index is swept.

Every step is recorded with its outcome in execution-<time>.md. A failed step does not stop the others.

All files of a plan live in ~/.somora/wiki-migration/<id>/, the backup in backup-<time>/ below it. They stay until you delete them.

To undo a run, use somora wiki migrate undo <id>. It moves the current wiki aside to <wiki>.before-undo-<time>, copies the backup back and sweeps the search index. Nothing is deleted.

Keeping an agent out ​

Every agent that dreams feeds the wiki. To keep one out, switch its dreaming off, in the Agent window or in its agent.yaml:

yaml
dreams: false   # no REM, no Deep; the wiki and the vault are read-only for it

See Who dreams.

A single note stays out with wiki_promote: false in its frontmatter.

Sync and limits ​

  • Sync is yours. The wiki is part of your vault. Use the sync you already use for it. somora runs on one host.
  • Do not sync the inboxes. Deep empties them. Synced to a second machine, a note one side just changed could be consumed by the other.
  • Your vault stays yours. Deep and Lucid never write outside the wiki folder, and Deep does not turn vault notes into wiki pages.
  • No chat logs. Deep skips notes that are only of the day: task lists, scratchpads, daily logs.
  • Splitting a page is manual. Lucid can propose moving or uniting pages. To split one page in two, edit it in Obsidian.

Settings ​

All settings live in config.yaml. The values shown are the defaults. Keys marked as comments have no default.

yaml
obsidian:
  # vault: ~/Documents/Vault
wiki:
  enabled: false
  vaultSubfolder: somora
  language: de
  # defaultSubdirs: [people, projects]
  deep:
    enabled: true
    intervalHours: 12
    # model: <model>
    # fallback: [<model>]
    # thinking: medium
    mergeShrinkGuard:
      enabled: true
      minRatio: 0.5
      minExistingBytes: 2000
    skipCacheDays: 30
    maxPageChars: 50000
    callTimeoutMs: 300000          # one model call; past it the next backup
  lucid:
    enabled: true
    intervalDays: 7
    # model: <model>
    # fallback: [<model>]
    # thinking: medium
    maxCallsPerTurn: 3
    batchChars: 100000
    oversizedChars: 50000
    maxFindings: 12
    autoLinks: true
    autoLinksPerRun: 30
    seenDays: 90
  search:
    boostWiki: 1.4
    boostMemory: 0.85
    boostVault: 0.65
    overviewMaxChars: 4000
    overviewTopNSlugs: 30
SettingMeaning
obsidian.vaultPath to the vault. Required for the wiki.
wiki.enabledSwitches the wiki on.
wiki.vaultSubfolderFolder inside the vault that is the wiki.
wiki.languagede or en. See Language.
wiki.defaultSubdirsStill read, but only shapes the example paths in the prompts. The folder template decides where pages go.
wiki.deep.enabledSwitches the scheduled Deep run on.
wiki.deep.intervalHoursHours between Deep runs.
wiki.deep.modelWorker model for Deep: an alias or <provider>/<model>.
wiki.deep.fallbackBackup model or list of models, tried in order when model cannot be reached. Best on another provider.
wiki.deep.thinkingoff, low, medium or high. Used when the model can reason. Unset means the engine's default.
wiki.deep.mergeShrinkGuard.enabledRefuse a merge that shrinks a page too much.
wiki.deep.mergeShrinkGuard.minRatioThe merge is refused when the new text is smaller than this share of the old one.
wiki.deep.mergeShrinkGuard.minExistingBytesPages smaller than this are never guarded.
wiki.deep.skipCacheDaysAn unchanged note that was skipped is looked at again after this many days. 0 means only when it changes.
wiki.deep.callTimeoutMsTime limit of one model call (one note), in milliseconds. Past it the note goes to the next backup. Default 300000.
wiki.deep.maxPageCharsA page over this size takes no more merges. The note becomes a sub-page.
wiki.lucid.enabledSwitches the scheduled Lucid run on.
wiki.lucid.intervalDaysDays between Lucid runs.
wiki.lucid.modelWorker model for Lucid. Also judges a migration. If unset, the migration uses wiki.deep.model.
wiki.lucid.fallbackAs wiki.deep.fallback.
wiki.lucid.thinkingAs wiki.deep.thinking.
wiki.lucid.maxCallsPerTurnMost wiki_* calls per turn in a review loop. Resets with every message of yours.
wiki.lucid.batchCharsMost page text one Lucid call carries. A larger page travels alone.
wiki.lucid.oversizedCharsPages over this size are reported as oversized.
wiki.lucid.maxFindingsMost findings a run keeps for review. Link suggestions fill what is left after the weightier kinds.
wiki.lucid.autoLinksLucid sets link suggestions itself: the first plain mention becomes a [[link]].
wiki.lucid.autoLinksPerRunMost links set per run.
wiki.lucid.seenDaysA finding you dismissed is not filed again for this many days.
wiki.search.boostWikiWeight of a wiki hit in recall.
wiki.search.boostMemoryWeight of a memory hit.
wiki.search.boostVaultWeight of a vault hit.
wiki.search.overviewMaxCharsSize budget of the overview block.
wiki.search.overviewTopNSlugsMost sections in stage 4 of the overview. The largest ones win.

Commands ​

The commands talk to the running server and leave the wiki to it, with one exception: migrate undo moves the current wiki aside and copies the backup back itself.

CommandWhat it does
somora wiki migrateGuided: plan, judge, approve, dry run, run.
somora wiki migrate planStep 1. Prints the plan id.
somora wiki migrate judge <id>Step 2. Waits for the model and lists the groups.
somora wiki migrate status <id>The groups and what is approved.
somora wiki migrate approve <id> --action move --action fold --twinsApproves all groups of an action (move, fold, unclear) and all same-name unions.
somora wiki migrate approve <id> --group fold:projects/house-build --dismissDismisses one group. A group key is move:<folder> or fold:<page>.
somora wiki migrate dry-run <id>Writes dry-run.md, touches nothing.
somora wiki migrate run <id> --confirm "move my wiki"The real run, with backup first.
somora wiki migrate undo <id>Puts the backup back. Asks for "yes" unless you pass --yes.
somora wiki migrate relink <id>A second pass over links and related entries with the renames of a finished run.

--url <server> picks the server. The default comes from SOMORA_URL or from the config.

Routes ​

When the wiki is not enabled, the explorer routes answer 503 and the migration routes 400. The request and response fields are in the API reference.

RouteWhat it does
GET /wiki/status{ enabled, root? }
GET /wiki/treeFolder tree with page titles.
GET /wiki/page?slug=<slug>Text, frontmatter, links, backlinks, broken links.
GET /wiki/graph?scope=local&slug=<slug>The page's neighbourhood.
GET /wiki/graph?scope=globalThe whole wiki.
POST /wiki/refreshDrops the cache and scans again.
POST /wiki/migration/planStep 1. Returns the plan id.
POST /wiki/migration/refineStep 2 for {id}. Runs in the background.
GET /wiki/migration/plans/:idPlan, progress, groups, approvals.
POST /wiki/migration/plans/:id/approveStep 3: groups, action or twins with status.
POST /wiki/migration/plans/:id/executeStep 4. Dry run by default. A real run needs {"dryRun": false, "confirm": "move my wiki"}.
POST /wiki/migration/plans/:id/relinkSecond pass over links and related.
POST /wiki/migration/reindexSweeps the search index now.

Pages are addressed by slug, never by file path. A request can only name a page the server already found under the wiki root, so ../ and absolute paths lead nowhere.

When something is off ​

SymptomWhat to check
No wiki tile, routes answer 503GET /wiki/status shows enabled: false. Set both wiki.enabled and obsidian.vault, then restart.
The agent does not know a new page existsIts overview is the one from session start. Start a new session or reset. The log line wiki.overview_failed means the overview could not be built.
A page you edited was not updated by DeepYour edit came between its read and its write. The note is tried again on the next run.
A note is never promotedIt was skipped and is looked at again when it changes or after skipCacheDays. Check for wiki_promote: false, and that the agent dreams (dreams: true).
Migration says "no model"Set wiki.lucid.model or wiki.deep.model.

See also ​

  • Memory: the per-agent inbox, recall and search ranking
  • Dream phases: how REM, Deep and Lucid work, and the review loop
  • Agents: agent.yaml, including dreams
  • Web client: the desktop the wiki window lives in
  • API: the wiki and migration routes in full
  • Cache strategy: why the overview is frozen per session