> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myrmagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Wiki Knowledge Base

> Manage structured knowledge with the Settings tree UI, hybrid search, and one-click save from chat.

# Wiki Knowledge Base

Myrm includes a **compiled knowledge base (Wiki)**—not a pile of markdown skills for the agent to interpret. A dedicated engine handles compile, index, search, review, and maintenance. The same workflow works on **Local WebUI**, **Tauri desktop**, and **SaaS cloud**.

## Wiki knowledge base

Build structured knowledge with a **compiler engine**—not a pile of markdown skills for the Agent to interpret. The same workflow runs on **local WebUI**, **Tauri desktop**, and **SaaS cloud**.

## Consumption loop

Myrm connects the wiki to the Agent through **12 code-level paths** (no manual AGENTS.md like OpenWiki):

* **Four tools auto-mounted** when Wiki is enabled on an agent profile (ingest / compile / query / maintain).
* **Large upload hints** inject wiki\_ingest → wiki\_query instructions so PDFs are not pasted into the chat context.
* **Deep Research vault** writes reports into the same wiki vault via the shared archiver and triggers compilation.
* **Save to Wiki** on any assistant message with provenance frontmatter.
* **Post-compaction session notes** — when context is compressed, session notes are automatically archived to the wiki (after summary persist, not on every note save).
* **Settings overview tab** for ad-hoc query, compile, maintain, and vault health badges.

## Memory → Wiki auto-bridge

When **Wiki is enabled** on an agent profile, four automatic ingress paths land in the same vault through **`publish_raw`** (Roadmap #16 — not separate toggles):

| Source                     | When                          | What happens                                                       |
| -------------------------- | ----------------------------- | ------------------------------------------------------------------ |
| **Deep Research**          | Research lane completes       | Report archived to vault → security scan → compile queue           |
| **Turn digest**            | SkillAgent end-of-turn review | High-signal digest published with `PUT_IF_ABSENT`                  |
| **Consolidation insights** | Memory consolidation callback | Structured insights bridged after dedup/subsumption                |
| **Session notes**          | Post-compaction archive       | Session notes archived after summary persist (not every note save) |

**Security & gates:** Every path runs **#15 archive security** (credential block/redact) and **#14 raw gate** (no silent overwrite on stable paths). Agent-level **`enable_wiki`** is the master switch — no per-source Settings toggles.

**Recall direction:** Wiki content is pulled into chat via **`knowledge_recall_tool(corpus=wiki|all)`** when both Wiki and Memory are enabled — not pushed into every turn like OpenClaw-style digest injection.

**Tests:** 37 targeted pytest (Harness 18 + Server 19, Jul 2026).

## Wiki vs Memory write boundary

When **both Wiki and Memory** are enabled, Myrm keeps long-form knowledge out of compact memory storage:

| Path                                    | Guard                                                                 | User effect                                           |
| --------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------- |
| Agent **`memory_save_tool`**            | Hard reject document-like knowledge/event (>800 chars or ≥3 headings) | Agent is told to use **`wiki_ingest_tool`** instead   |
| **End-of-turn auto-extract**            | Same heuristics at persist time + extraction prompt skip              | Long article summaries do not pollute semantic memory |
| **Save to Wiki** / **External Sources** | Product paths for long content                                        | Gmail/Drive/RSS/chat → vault raw → optional compile   |

**vs Hermes:** flat MEMORY.md with a **2,200-character cap** — no compiled wiki vault or unified `corpus=all` search.

**Tests:** 25 targeted pytest (Harness wiki boundary module, Jul 2026).

## Karpathy cognitive map trio (index / log / hot)

After compile, maintain, import, or human review, the engine **deterministically** maintains three vault-root files (zero extra LLM cost):

| File         | Role                                                                                | User benefit                                                                          |
| ------------ | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| **index.md** | Concept catalog grouped by page `type`; summaries prefer L0 `.abstract.md` sidecars | Browse in Obsidian or any editor; migrated users see a structured vault               |
| **log.md**   | Human-readable audit trail, newest first                                            | Trace when compile/import/approve happened                                            |
| **hot.md**   | Recent ops, pending compile queue, review hints                                     | Settings query and `wiki_query` honestly surface vault status when FTS finds no match |

**Honest differentiation vs competitors:**

* **Stronger than Molio**: hot is used only on the wiki query path — **not** injected into the agent global system prompt → safer prompt cache
* **Stronger than Hippocampus**: event-driven refresh, not blind per-session hot inject
* **Intentionally not**: Molio-style LLM hot rewrite (token/hallucination cost); global middleware hot (breaks cache)

Settings **Overview** auto-loads trio readiness stats — no CLI required.

## Unified vault path

All wiki data lives under a **single vault directory** per workspace. Settings, REST API, Agent tools, Save to Wiki, Deep Research, and compaction archive share the same path. On startup, legacy paths are migrated automatically.

In **Settings → Wiki → Overview**, stats load on page open and show:

* **Vault ready** — the wiki directory exists and is writable.
* **Legacy migrated** — any old vault location was merged into the current path.
* **Knowledge catalog / Activity log / Recent context** — whether the Karpathy-style trio (`index.md`, `log.md`, `hot.md`) is built and fresh after compile, import, or review actions.

This replaces ad-hoc CLI “doctor” checks with in-product health visibility.

## Project vault (file-centric SSOT) vs Wiki import

**Two different paths — pick the one that matches your workflow:**

| Goal                                                          | Use                                                                                          | User benefit                                                                     |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| Keep editing in Obsidian/Typora/VSCode on **your disk**       | **Settings → Projects → Mount sync folder** (or Migration Result bind after OpenClaw import) | Agent reads/writes the **same files** you edit; Files tab auto-refreshes via SSE |
| Copy notes into Myrm’s **compiled Wiki DB** for hybrid search | **Settings → Wiki → Import Obsidian/ZIP**                                                    | Great for search/compile/HITL review — **not** a live sync mirror                |

After competitor migration, use the **Migration Result vault bind card** so your first chat already points at the real vault — no manual Project setup.

Per-chat **task scope** (without creating a Project): use the **folder icon** in the message composer (`WorkspaceDirPicker`) to bind a directory for this conversation.

## Per-agent wiki scope

Each agent can have its **own wiki vault**. In **Settings → Wiki**, use the **Agent scope** dropdown (or open `/settings/wiki?agentId=<agent-id>` from the agent banner). Stats, compile, maintain, and imports apply to the selected agent only.

Artifact **Save to Wiki** and chat-bound ingest use the **current chat’s agent id**, so documents do not land in the default vault by mistake.

**Honest boundary (until Agent Scope SSOT v2 ships):** the **Queue** tab and ingest SSE follow the selected agent immediately. If you switch agents while staying on **Pending** or **Concepts**, reload the page or switch tabs until scope reload is fully wired — approving a draft against the wrong vault is the risk we are closing in the next scope hardening release.

## Unified memory + wiki recall

When **both Wiki and Memory** are enabled on an agent profile, Myrm mounts a unified **`knowledge_recall_tool`** with `corpus=all` — one tool call searches long-term memory and the agent wiki together. Memory hits emit **cited memory IDs** for the UI; wiki hits appear in the tool result text.

Default agent profiles include Memory; enable Wiki in **Agent config → Built-in tools** to get the unified path.

## Memory citation button (reload-safe)

When the agent recalls semantic/episodic memories, completed assistant messages show a **Memory N** button in the action bar. Open the sheet to inspect which memories influenced the answer (type, score, namespace, link back to source chat).

Citations are **persisted to the database** and survive **page reload** — not SSE-only ephemeral state.

## Open Wiki settings

1. Go to **Settings → Wiki 知识库 (Wiki)**.
2. Use the tabs:
   * **Overview** — purpose, stats, compile/maintain actions, ad-hoc query.
   * **Concepts (词条管理)** — folder tree, CRUD, drag-and-drop.
   * **Pending edits** — human-in-the-loop approve/reject for LLM drafts.
   * **Queue** — document ingestion pipeline status.

## Live compile visibility (Settings open)

When **Settings → Wiki** is open in the browser or desktop app:

| Surface                         | What updates live                                                                                                                                                                                                                                                           | User benefit                                                                                         |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| **Queue tab**                   | SSE stream (`GET /wiki/ingest/stream`) pushes queue counts + compile circuit state (\~5s). **Compile phase bar** shows structure survey → semantic compile → post-process (facet count / fast-path label when applicable). Failed-item list auto-resyncs if counts diverge. | See batch progress without clicking Refresh; API key expiry shows an amber pause banner with resume. |
| **Overview compile actions**    | Same SSE `compile_run.phase` drives a shared phase bar above Compile/Maintain while bulk ingest runs.                                                                                                                                                                       | Primary compile path shows progress without switching to Queue tab.                                  |
| **Overview → Raw sources tree** | Ingest status dots refresh during bulk compile (`tree_sync_required` → silent `GET /wiki/raw/tree`).                                                                                                                                                                        | Gray/green/amber dots track "not compiled / clean / modified" while files are still processing.      |
| **Concepts tab tree**           | Same signal triggers concept-tree reload when that tab is mounted.                                                                                                                                                                                                          | Amber dots on concepts with stale sources update as compile finishes.                                |

<Note>
  Live updates require the Settings Wiki page to stay open (EventSource subscription). Closing Settings stops SSE — this is intentional GUI-scope visibility, not a background daemon. Competitors with CLI-only or file-tree-only wikis (Hermes SKILL, OpenClaw markdown folders) do not offer an equivalent Queue panel + live ingest badges.
</Note>

## External source sync (Settings Overview)

**Settings → Wiki → Overview → External sources** pulls saved mail and feeds into `wiki/raw/` on a schedule or on demand:

| Source                  | What you configure                                                                        | What happens                                                        |
| ----------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| **Gmail label**         | Connect Google in Integrations; enable Gmail sync; type the label name (case-insensitive) | Messages under that label become Markdown under `wiki/raw/gmail/`   |
| **Google Drive folder** | Connect Google in Integrations; enable Drive sync; paste folder ID (`root` = My Drive)    | Docs/Sheets/Slides/PDFs export to Markdown under `wiki/raw/gdrive/` |
| **RSS**                 | One URL per line                                                                          | Entries land under `wiki/raw/rss/`                                  |
| **Integration mirror**  | Toggle on when integrations sync                                                          | New integration items can mirror into raw                           |

**Zero-LLM pull:** fetching Gmail/RSS does **not** call your chat model. Optional **Auto-compile after sync** only uses LLM when a model is configured.

**Cron:** the **Read-it-later ingestion** blueprint runs daily (often paired with **Wiki morning delta** via Second Brain preset). Router job `__wiki_source_sync__` executes server-side with **no agent tools** — safe, deterministic automation.

**Observability:** last sync time, published/skipped/failed counts, and the first error line (e.g. `Gmail label not found`) appear on the card.

<Note>
  **Honest boundary:** Gmail labels and Drive folder IDs are typed manually — there is no label dropdown or Drive Picker. Create a matching label in Gmail (default preset uses `ReadLater`). If Google is connected but Drive read scope is missing, the card shows a **reconnect hint** (`google_drive_authorized: false`). **OneDrive is not supported** (no Microsoft OAuth infra). Misconfiguration is surfaced on sync, not silently ignored.
</Note>

**Tests (2026-07-30):** gdrive 3 + gmail/rss/status/oauth 12 + state/config/defaults/blueprint/hygiene/second\_brain 15 + gmail\_html 2 = **32 pytest passed** (mock Gmail/Drive API; no Chrome MCP this round).

## Evolution synthesis at compile (CCSP)

When you **Compile Wiki**, Step 2.5 runs a **Compile-Time Contradiction Synthesis Pass** after normal article generation:

| Step                        | What happens                                                                                              | User benefit                                                                            |
| --------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| **Pairing (zero LLM)**      | Related concepts and shared slugs are paired                                                              | No extra token cost for obvious candidates                                              |
| **Detection (LLM, capped)** | Up to 3 high-confidence cross-concept factual conflicts per compile                                       | Surfaces "these two pages disagree" without you reading every note                      |
| **Staging (HITL)**          | Draft evolution pages land in **Pending edits** — not auto-published                                      | You choose priority before anything hits the vault (stronger than auto-write tutorials) |
| **Approve → backlinks**     | Both linked concepts get a Timeline entry pointing at `Comparisons/.../Evolution`                         | Trace conflicts from either side in Obsidian or the tree GUI                            |
| **Overview badge**          | Violet count on Overview when synthesis drafts exist; click → Pending with **Evolution synthesis** filter | No need to hunt the Pending tab after every compile                                     |

**Live count:** ingest SSE exposes `synthesis_pending_count`; Overview refreshes without a full page reload when Settings → Wiki stays open.

**Honest differentiation vs OpenClaw:** OpenClaw writes `reports/contradictions.md` and expects CLI follow-up. Myrm keeps the same intelligence in **Settings Pending + GUI filters + bidirectional Timeline links** — better for Article 8-style "decide which definition wins" workflows.

**Honest boundary:** Cross-concept only (same-batch name merges are skipped). This is Wiki compile synthesis, not the separate Memory **ConflictCard** notification path.

**Tests (2026-07-29):** Harness 8 (`test_contradiction_synthesis`) + 12 (`test_linter_extended`) + Server 2 (stats/pending API) = **22 passed**. Browser MCP E2E not run this round.

## Manage concepts in the tree

In **Concepts**:

* **New folder** — pick an optional parent folder (root or nested), then name the folder.
* **Rename / delete** — hover a row; delete shows the full path and how many items inside will be removed.
* **Drag and drop** — move folders or concepts between parents (link refs are updated server-side).
* **Detail panel** — select a concept to view rich-rendered content (Mermaid diagrams, KaTeX math, GFM tables, syntax-highlighted code blocks, and dark mode) or switch to raw Markdown editing.
* **Four-tab editor (Edit)** — narrow writes via `POST /wiki/apply` (not full-page PUT):
  * **Compiled Truth** — patch the `## Compiled Truth` section only.
  * **Timeline** — append-only entries; duplicate lines are skipped with a toast.
  * **Metadata** — replace tags and aliases in frontmatter (Settings path; Agent merge uses a different caller gate).
  * **Advanced** — full-page replace; **Settings-only** (`caller=settings`). Agent and chat cannot use this op.

Each save sends the page **lease** (`if_match` = last known `content_hash`). If another tab or client changed the page first, you get a **page conflict** toast — reload and retry.

## Controlled write surface (`POST /wiki/apply`)

All wiki mutations go through one REST endpoint: **`POST /wiki/apply?caller=`** (`settings` | `agent` | `chat`).

| Operation               | Who                                | What it does                                               |
| ----------------------- | ---------------------------------- | ---------------------------------------------------------- |
| `create_note`           | Save to Wiki, Agent (opt-in)       | New concept with managed sections + provenance frontmatter |
| `update_metadata`       | Settings Metadata tab; Agent merge | Tags / aliases / sources / claims                          |
| `patch_compiled_truth`  | Settings Truth tab                 | Replace Compiled Truth block only                          |
| `append_timeline`       | Settings Timeline tab              | Append-only Timeline with dedup guard                      |
| `replace_full_document` | Settings Advanced tab only         | Full page replace — **403** for agent/chat callers         |

**Write-time dedup:** `canonical_id` and alias index reject near-duplicate pages on create (HTTP 409 `canonical_conflict`). Save to Wiki shows a friendly toast when a note on the same topic already exists.

**Honest boundary:** Agent `wiki_apply_tool` still uses CSV-style parameters and does not auto-send `if_match`; the Settings GUI and Save to Wiki paths are complete.

## Raw evidence layer gate (import & ingest)

Stable-path writes to `wiki/raw/` go through the harness **`publish_raw`** gate — complementary to concept-layer `POST /wiki/apply` (#12+#13).

| Scenario                              | Default behavior                                                       | User benefit                                                     |
| ------------------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------- |
| **Re-import** Folder / ZIP / Obsidian | Skip files that already exist with **different** content               | Your curated raw notes are not silently overwritten              |
| **Conflict dialog**                   | Lists skipped paths; optional **Supersede all** with a required reason | Explicit decision in GUI — no filesystem detective work          |
| **Audit trail**                       | Supersede events append to **`wiki/log.md`**                           | Trace why a raw source was replaced                              |
| **Agent ingest**                      | `wiki_ingest` with `caller=agent`                                      | High-confidence prompt injection is **blocked** before raw write |
| **Unchanged files**                   | Same content hash → skip without re-compile                            | Saves LLM compile cost on repeat imports                         |

**Honest boundary:** Timestamp/uuid raw paths (research dumps, artifact ingest, session archive) are intentionally ungated — no stable-path conflict. There is no dedicated Raw Audit panel; read `wiki/log.md` or use Overview stats.

## Archive security governance (sensitive content)

All durable Wiki writes share the harness persistence scan SSOT (`core/security/persistence/content_scan.py`):

| Stage                                 | Gate                                                   | User benefit                                                                                      |
| ------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
| **Import / ingest / session archive** | `publish_raw` pre-scan (`WIKI_RAW`)                    | API keys and credential-shaped text are **blocked** or **redacted** before landing in `wiki/raw/` |
| **编译发布**                              | `publish_concept_article`（`WIKI_PUBLISH`）              | 不可脱敏凭证不会静默成为 canonical 页                                                                          |
| **Settings import feedback**          | `WikiImportSecurityDialog`                             | Lists blocked/redacted paths after folder/ZIP/Obsidian import — no silent drops                   |
| **Forget evidence**                   | Overview raw tree → reason → `DELETE /wiki/raw/{path}` | Remove mistaken imports; dependent compiled pages are re-anchored; event logged to `wiki/log.md`  |
| **Maintenance**                       | `wiki_maintain` scans existing raw vault               | Catches legacy files; **blocked credentials are removed** from disk (not count-only)              |

**Honest boundary:** No security stats dashboard yet; Settings/chat import injection is warn-only; **agent `wiki_ingest` blocks high-confidence injection**. Agent blocked paths surface as tool errors, not a Settings dialog.

<Note>
  Wiki files remain plain Markdown on disk. Obsidian and other editors can open the same vault; Myrm adds indexing, search, and GUI management on top.
</Note>

## Reference Wiki in chat with @wiki:

Type `@wiki:` in the chat input to search your Wiki concepts with live autocomplete. Select a concept to inject its compiled content as context for the current message:

* **`@wiki:keyword`** — filters the dropdown to show only matching Wiki concepts (fuzzy match on concept name).
* **Select a concept** — the input becomes `@wiki:ConceptName` with a removable pill tag, just like `@staged` or `@diff`.
* **The Agent receives** the concept content in a `<mentioned_files>` XML block, grounding its answers in your knowledge base.
* **Combine references** — `@wiki:ProjectArchitecture @staged` sends both the wiki article and your git staged changes in one message.
* **Plain `@` search** — typing `@keyword` (without the `wiki:` prefix) shows a mixed list of agents, wiki concepts, and uploaded files.

This gives you explicit, per-message control over which knowledge the Agent uses — no reliance on automatic retrieval or prompt engineering.

## Save a chat message to Wiki

On any **completed assistant message**, use **Save to Wiki** (book icon) in the message action bar:

1. Choose a filename and optional target folder in the tree picker.
2. Confirm save — content is written via **`create_note`** on `POST /wiki/apply` (managed Compiled Truth + Timeline skeleton).
3. Each save adds YAML frontmatter: `source_chat`, `source_message`, `saved_at` for traceability.
4. If a note with the same **canonical topic** already exists, you get a **canonical conflict** toast instead of silently creating a duplicate page.

## Page type contract (frontmatter `type`)

Every wiki page must declare a **page type** in YAML frontmatter. This is enforced at compile time, on pending-edit approval, and by the linter — not just a prompt suggestion.

**Allowed values:** `source`, `entity`, `concept`, `comparison`, `overview`, `question`, `session` (Google OKF–compatible subset).

| When                  | What happens                                                                                                |
| --------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Compile**           | LLM output passes through a compile gate; missing `type` defaults to `concept`, invalid values are rejected |
| **Pending approve**   | Approve returns **422** if frontmatter is invalid; the UI shows a friendly error                            |
| **Maintain / Linter** | Auto-detects missing or invalid `type` and can repair on maintain                                           |
| **Repair Page Types** | Settings → Wiki → **Repair Page Types** scans the vault and infers types for legacy notes                   |
| **Obsidian import**   | Types are inferred from path/content heuristics; writeback preserves `type`, `sources`, and `provenance`    |

**Honest boundary:** Save to Wiki from chat currently writes provenance fields only (`source_chat`, etc.); run **Repair Page Types** or **Maintain** to backfill `type` on those notes. Settings Advanced full-page replace is not hard-blocked on frontmatter — the linter heals drift on the next maintain pass.

This closes the loop: **conversation → one-click archive → searchable knowledge**.

## Search and maintain

* **Query Wiki** (Overview tab) — natural-language answers with **zero LLM** on the query path: seeds from the cognitive index, sidecar summaries, FTS5, and keywords converge through a budgeted best-first graph expansion before assembling L0/L1/L2 snippets and claim/evidence cards.
* **Retrieval mode** (Overview → Query Wiki) — choose **General** (balanced across index, directories, and articles) or **Claims first** (boost concepts with structured frontmatter claims and linked evidence; falls back to General when no claim match). OpenClaw offers similar `raw-claim` behavior via CLI only; Myrm exposes it in Settings without memorizing flags.
* **Citation trust** — answer cards include claim text, evidence paths, and `snapshot_status` so you can see whether cited content still matches the vault on disk.
* **Evidence citation Drawer (Closure v2)** — tap a citation chip in Chat or Settings: claim status badges (contested/unsupported only, to reduce noise), **compile confidence %** when explicitly set, and **raw excerpt** blocks. Retrieval ranks fresh supported claims ahead of stale contested ones with zero LLM cost.
* **Settings retrieval path trace** — below Query results, a card shows index hits, seeds, sidecar directories, and selected concepts so power users can debug “why this concept matched.”
* **Compile / Maintain** — incremental compile (SHA256 change detection), parallel batch ingestion (Semaphore-limited concurrency for \~40% faster multi-document processing), visual element guidance (the compiler prompts the LLM to produce Mermaid diagrams, GFM tables, and fenced code blocks where appropriate), and linter-driven health fixes (broken links, drift, stale content, knowledge-gap detection for isolated/bridge concepts).
* **Structural health stats** (Overview tab) — zero-LLM scan counts broken markdown links, broken Obsidian `[[wikilink]]` targets (path + unique title alias), and missing frontmatter `type` values. Amber badges update after compile, import, concept edits, pending approvals, and folder deletes — no CLI `wiki lint` required. CI runs a 4-case retrieval regression gate on every harness change.
* **Library / Brain views** — 3D knowledge graph with community detection and concept exploration (product navigation may vary by deployment).
* **Knowledge graph** — the compiler auto-extracts concepts and their relationships, building a graph with weighted edges (direct link + source overlap + common neighbors). LPA community detection groups related concepts; gap analysis highlights isolated nodes and bridge concepts that connect otherwise separate domains.
* **Smart context recall** — when starting a new conversation, the agent automatically recalls relevant memories and knowledge based on the current topic, so you never need to manually point it to the right documents.
* **Contradiction detection** — the Claim Graph tracks `contradiction_status` and `CONTRADICTED_BY` relationships across knowledge entries. Consolidation automatically flags conflicting facts for human review rather than silently overwriting.
* **Federated search** — when multiple wiki namespaces or published directories exist, queries search across all sources and merge results with RRF ranking, ensuring comprehensive coverage without manual scoping.

## Import from Obsidian

Myrm provides a dedicated **Obsidian Vault importer** that preserves your notes, tags, and images:

1. In **Settings → Wiki**, scroll to the import section.
2. **Tauri desktop**: click **Import Obsidian Vault** and select the local vault directory.
3. **WebUI / Cloud**: click **Upload Obsidian ZIP** and upload the vault as a `.zip` file.

The importer handles:

* **YAML frontmatter** — both inline arrays (`tags: [a, b]`) and YAML indented lists (`tags:\n  - a\n  - b`), including `aliases`, `created`, and `updated`.
* **Image embeds** — `![[image.png]]` syntax is rewritten to standard Markdown and images are copied to the wiki assets directory.
* **`.canvas` files** — empty boards or boards with no extractable text are skipped; boards with text nodes are converted to Markdown (text content and file/link labels per JSON Canvas 1.0).
* **Encoding resilience** — files that fail UTF-8 decoding are reported but do not block the import.
* **Conflict-safe re-import** — if a raw file already exists with different content, it is **skipped by default**. A dialog lets you supersede with a reason (logged to `wiki/log.md`).

After import completes, a toast notification shows the number of notes processed, tags extracted, and images migrated. The imported files enter the compilation queue and are automatically indexed.

## Open in Obsidian & export pack (#22 + #22b)

The **Obsidian Vault** card on **Settings → Wiki → Overview** complements import above with reverse open/export:

| Action                     | Local / Tauri                                                                                                              | Cloud                              |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| **Open in Obsidian**       | When Obsidian is installed (`obsidian_launch_available`) — macOS `open -a`, Windows `%LocalAppData%`, Linux `obsidian` CLI | Hidden (not available)             |
| **Show in folder**         | Reveal wiki directory in Finder / Explorer / file manager                                                                  | Hidden                             |
| **Copy vault path**        | Copy `{harness_dir}/wiki/agents/{agent}/`                                                                                  | Hidden                             |
| **Download Obsidian pack** | Full vault ZIP + `.obsidian/graph.json` (colorGroups by frontmatter `type`) + `README-OBSIDIAN.txt`                        | Same (open locally after download) |

After unzip: **Obsidian → Open folder as vault** → Graph view shows nodes colored by page type.

**Tests (Jul 2026):** 14 targeted pytest (cross-platform launch + reveal + export — no Chrome MCP E2E).

<Note>
  **vs Project mount:** To keep editing on **your own disk** with Obsidian/Typora, use **Settings → Projects → Mount sync folder**. #22 is for **Myrm-hosted compiled vaults** — one-click open or snapshot export.
</Note>

<Note>
  **Honest limits:** Cloud cannot reveal local paths; Open button hidden when Obsidian is not installed (Show in folder + Download still work); Windows `%ProgramFiles%\Obsidian\Obsidian.exe` is not probed yet; no portable `obsidian://` deep links.
</Note>

## Local vault git snapshots (#23)

When **version control** is enabled on a wiki vault (Local/Tauri defaults it on for session archive and similar paths), Myrm keeps a **real `.git` directory inside the vault** — not a shadow-git plugin:

| What                     | When                                                                                    | User benefit                                                 |
| ------------------------ | --------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| **Auto-commit**          | Compile, import, apply, approve, delete, and other vault mutations (13 SSOT hook sites) | Auditable history without manual `git init`                  |
| **Overview hint**        | Settings → Wiki → Overview                                                              | Shows latest snapshot commit hash when git is active         |
| **Standard git tooling** | Any git client or Obsidian Git plugin                                                   | `git log` / `git blame` work on the same files Myrm compiles |

**Tests (Jul 2026):** 5 targeted pytest for vault git (`test_wiki_vault_git_mutation` 2 + Harness `test_vault_git` 3 — no Chrome MCP E2E).

<Note>
  **Honest limits:** No in-Settings commit list UI — use `git log` or Obsidian Git for deep history. Download Obsidian pack ZIP does **not** include `.git`. Cloud deployments do not promise vault git.
</Note>

## Search imported images (Obsidian assets)

When **Vision Fallback Model** is configured under **Settings → Models**, Myrm indexes images under `wiki/assets/` with vision-generated captions (FTS5 + optional vector hybrid). You can find them without a separate image-search tool:

* **`wiki_query` / `knowledge_recall(corpus=wiki|all)`** — text questions like “where is the architecture diagram?” can return asset hits with captions and **thumbnail citations** in Chat Sources.
* **Settings → Wiki → Overview** — `asset_index` badges show indexed / pending / failed counts; if images exist but vision is not configured, an amber hint links you to Models.
* **Import path** — Obsidian import schedules background asset indexing; compile/maintain also refreshes the asset index.

<Note>
  **Honest limits:** This is **text → image** search via captions, not **image → image** (multimodal embed). Competitors like OpenViking offer the latter; general claw agents (OpenClaw, Hermes) lack this Obsidian asset caption pipeline entirely. Without vision configured, assets are imported but not searchable — the Overview hint covers that case; Chat will not show misleading empty-caption asset sources.
</Note>

## URL ingestion and video subtitle extraction

When ingesting URLs into the Wiki, Myrm routes all links through the **CrawlEngine**:

* **YouTube videos** — subtitles are automatically extracted (10+ languages supported). The wiki stores searchable text, not raw HTML.
* **Bilibili videos** — subtitle extraction via direct API, no DOM parsing needed.
* **WeChat articles** — multi-tier fetcher automatically handles anti-crawl protections (HTTP → browser → stealth mode progressive degradation).
* **Regular web pages** — CrawlEngine adaptively selects the optimal fetching strategy; JS-rendered pages are automatically upgraded to the browser engine.
* **High-availability fallback** — if CrawlEngine fails, the system automatically falls back to `secure_get` + Markdown conversion, ensuring ingestion is never blocked.

Users simply share a link with the Agent and say "import this" — the system automatically identifies the URL type and selects the optimal extraction method.

## Document parsing and OCR

When ingesting documents into the Wiki, Myrm automatically selects the optimal parsing strategy:

* **Text-rich PDFs** — extracted via pdfplumber with parallel processing, bookmark injection, and font-based heading detection.
* **Scanned PDFs** — auto-detected when text content is sparse (\< 200 characters). Pages are rendered as PNG images and sent to your vision model (VLM) for understanding.
* **Hybrid PDFs** — text is extracted normally while embedded charts and photos are also captured and filtered through the smart image ablation filter (removes UI noise, logos, decorative elements).
* **Images** — local PaddleOCR engine supports Chinese, Japanese, Korean, and English with no cloud dependency. Results include confidence scores and bounding boxes.
* **Office files** — native parsers for DOCX, XLSX, PPTX without external dependencies like MarkItDown.

All strategies run asynchronously and feed into the same compilation pipeline — no manual selection required.

## Security

Wiki ingestion is protected by **path traversal defense** and **persistence-layer content scanning**:

1. **Filename sanitization** — any directory components in LLM-provided filenames are stripped (`Path(filename).name`), preventing an injected tool call from targeting paths like `../../../etc/cron.d/evil.md`.
2. **Boundary validation** — `safe_join_path()` validates that resolved paths stay within the wiki raw directory, blocking absolute paths, null byte injection, symlink escapes, and `../` traversal.
3. **Pre-write scan** — `publish_raw` and compiled publish run credential / injection checks before bytes hit disk (see **Archive security governance** above).

These defenses operate at the harness framework level, meaning all wiki ingestion paths (agent tool calls, auto-archive, Settings import, large document RAG ingest) are automatically protected. The wiki directory itself lives outside the user home directory and is further isolated by OS-level sandboxing (macOS Seatbelt / Linux bubblewrap / Windows AppContainer) during code execution.

## Compared to DIY wiki skills

| DIY (e.g. Hermes llm-wiki SKILL)                    | Myrm                                            |
| --------------------------------------------------- | ----------------------------------------------- |
| Agent must follow hundreds of lines of instructions | Python engine runs compile/search/lint reliably |
| Manual folder layout                                | Settings tree GUI + APIs                        |
| Copy/paste good answers                             | Save to Wiki button + provenance metadata       |
| Obsidian required for graphs                        | Built-in 3D graph + web Settings                |

<Warning>
  Myrm does not yet offer a Notion-style recycle bin for Wiki deletes. Treat delete confirmations seriously; use backups for critical notes.
</Warning>

## Related

* [Memory system](/docs/core-concepts/memory-system) — episodic/semantic memory vs compiled Wiki articles
* [Competitor comparison](/docs/getting-started/competitor-comparison) — migration and positioning