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:
# ~/.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 LucidYou 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 logThis 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
| Writer | When | What it does |
|---|---|---|
| Deep | every 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. |
| Lucid | every 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 review | when you start dream_review | Walks the Lucid findings with you and changes pages with wiki_edit, wiki_create, wiki_delete and wiki_move after you agree to each step. |
| You | any time | Edit 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
---
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]]| Field | Required | Meaning |
|---|---|---|
slug | yes | Path inside the wiki without .md. Matches the file's location. |
type | yes | Loose category. Deep prefers person, project, concept, place, tool (de: person, projekt, konzept, ort, werkzeug) and may use others. |
created | yes | Date the page was created. |
updated | yes | Date of the last change. Refreshed on every write. |
sources | no | <agent>/<memory-slug> entries: which inboxes contributed. |
related | no | Other wiki pages, as paths without .md. |
New pages get four sections. You can add others: a merge keeps the structure a page already has.
en | de | Content |
|---|---|---|
## Current state | ## Aktueller Stand | a short summary in prose |
## Properties | ## Eigenschaften | stable facts as a list |
## Timeline | ## Zeitleiste | dated entries |
## Notes | ## Notizen | everything 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.
en | de | What 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-reservewhilecompanies/acmeexists 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).
# 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: addressThe 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
| Way | What the agent gets |
|---|---|
| Automatic recall | Wiki 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 block | A map of what the wiki holds, in the system prompt. |
| Tools | memory_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:
| Stage | Content | Used when |
|---|---|---|
| 1 | index.md as it is | it fits the budget |
| 2 | sections, pages, descriptions cut to 100 characters | small wiki |
| 3 | sections and bare page links | medium wiki |
| 4 | section names with page counts | large 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
typevalues of new pages - the folder template and the name of the structure file
- the wording of
index.mdand 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.
| Column | What it shows |
|---|---|
| Tree | Folders and pages, a filter box, a re-scan button and the page count. |
| Page | The rendered page. [[links]] open inside the window. |
| Graph | The 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.
- Plan. Reads the wiki and writes
plan.md: folders a rule would move (a folder namedstocksbelongs infinances/portfolio), page names that exist in several folders, and dated work reports with the project they seem to belong to. Nothing is touched. - 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. - 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.
- Execute. The default is a dry run that writes
dry-run.mdand nothing else. The real run does the steps below.
A real run, in this order:
| Step | What happens |
|---|---|
| Backup | A full copy of the wiki, checked by file count. No copy, no run. |
| Moves | The file moves and its slug follows. |
| Folds | The 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. |
| Unions | Of two same-name pages one survives with a merged text. The other goes to the same archive. |
| Links | Every [[link]] and related entry is pointed at the new places. |
| Cleanup | Empty 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:
dreams: false # no REM, no Deep; the wiki and the vault are read-only for itSee 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.
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| Setting | Meaning |
|---|---|
obsidian.vault | Path to the vault. Required for the wiki. |
wiki.enabled | Switches the wiki on. |
wiki.vaultSubfolder | Folder inside the vault that is the wiki. |
wiki.language | de or en. See Language. |
wiki.defaultSubdirs | Still read, but only shapes the example paths in the prompts. The folder template decides where pages go. |
wiki.deep.enabled | Switches the scheduled Deep run on. |
wiki.deep.intervalHours | Hours between Deep runs. |
wiki.deep.model | Worker model for Deep: an alias or <provider>/<model>. |
wiki.deep.fallback | Backup model or list of models, tried in order when model cannot be reached. Best on another provider. |
wiki.deep.thinking | off, low, medium or high. Used when the model can reason. Unset means the engine's default. |
wiki.deep.mergeShrinkGuard.enabled | Refuse a merge that shrinks a page too much. |
wiki.deep.mergeShrinkGuard.minRatio | The merge is refused when the new text is smaller than this share of the old one. |
wiki.deep.mergeShrinkGuard.minExistingBytes | Pages smaller than this are never guarded. |
wiki.deep.skipCacheDays | An unchanged note that was skipped is looked at again after this many days. 0 means only when it changes. |
wiki.deep.callTimeoutMs | Time limit of one model call (one note), in milliseconds. Past it the note goes to the next backup. Default 300000. |
wiki.deep.maxPageChars | A page over this size takes no more merges. The note becomes a sub-page. |
wiki.lucid.enabled | Switches the scheduled Lucid run on. |
wiki.lucid.intervalDays | Days between Lucid runs. |
wiki.lucid.model | Worker model for Lucid. Also judges a migration. If unset, the migration uses wiki.deep.model. |
wiki.lucid.fallback | As wiki.deep.fallback. |
wiki.lucid.thinking | As wiki.deep.thinking. |
wiki.lucid.maxCallsPerTurn | Most wiki_* calls per turn in a review loop. Resets with every message of yours. |
wiki.lucid.batchChars | Most page text one Lucid call carries. A larger page travels alone. |
wiki.lucid.oversizedChars | Pages over this size are reported as oversized. |
wiki.lucid.maxFindings | Most findings a run keeps for review. Link suggestions fill what is left after the weightier kinds. |
wiki.lucid.autoLinks | Lucid sets link suggestions itself: the first plain mention becomes a [[link]]. |
wiki.lucid.autoLinksPerRun | Most links set per run. |
wiki.lucid.seenDays | A finding you dismissed is not filed again for this many days. |
wiki.search.boostWiki | Weight of a wiki hit in recall. |
wiki.search.boostMemory | Weight of a memory hit. |
wiki.search.boostVault | Weight of a vault hit. |
wiki.search.overviewMaxChars | Size budget of the overview block. |
wiki.search.overviewTopNSlugs | Most 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.
| Command | What it does |
|---|---|
somora wiki migrate | Guided: plan, judge, approve, dry run, run. |
somora wiki migrate plan | Step 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 --twins | Approves all groups of an action (move, fold, unclear) and all same-name unions. |
somora wiki migrate approve <id> --group fold:projects/house-build --dismiss | Dismisses 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.
| Route | What it does |
|---|---|
GET /wiki/status | { enabled, root? } |
GET /wiki/tree | Folder 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=global | The whole wiki. |
POST /wiki/refresh | Drops the cache and scans again. |
POST /wiki/migration/plan | Step 1. Returns the plan id. |
POST /wiki/migration/refine | Step 2 for {id}. Runs in the background. |
GET /wiki/migration/plans/:id | Plan, progress, groups, approvals. |
POST /wiki/migration/plans/:id/approve | Step 3: groups, action or twins with status. |
POST /wiki/migration/plans/:id/execute | Step 4. Dry run by default. A real run needs {"dryRun": false, "confirm": "move my wiki"}. |
POST /wiki/migration/plans/:id/relink | Second pass over links and related. |
POST /wiki/migration/reindex | Sweeps 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
| Symptom | What to check |
|---|---|
| No wiki tile, routes answer 503 | GET /wiki/status shows enabled: false. Set both wiki.enabled and obsidian.vault, then restart. |
| The agent does not know a new page exists | Its 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 Deep | Your edit came between its read and its write. The note is tried again on the next run. |
| A note is never promoted | It 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, includingdreams - 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