From 9eacd29138a7d22944268f1a0ccfa8eaf18df24f Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Wed, 8 Apr 2026 03:59:18 +0100 Subject: [PATCH] docs: add memory wiki docs --- docs/.i18n/glossary.zh-CN.json | 8 + docs/cli/index.md | 14 ++ docs/cli/memory.md | 2 + docs/cli/wiki.md | 214 ++++++++++++++++++++ docs/concepts/memory.md | 30 +++ docs/plugins/memory-wiki.md | 357 +++++++++++++++++++++++++++++++++ 6 files changed, 625 insertions(+) create mode 100644 docs/cli/wiki.md create mode 100644 docs/plugins/memory-wiki.md diff --git a/docs/.i18n/glossary.zh-CN.json b/docs/.i18n/glossary.zh-CN.json index c5e1681d358..cc591c0b98f 100644 --- a/docs/.i18n/glossary.zh-CN.json +++ b/docs/.i18n/glossary.zh-CN.json @@ -183,6 +183,14 @@ "source": "Doctor", "target": "Doctor" }, + { + "source": "Memory Wiki", + "target": "Memory Wiki" + }, + { + "source": "wiki", + "target": "wiki" + }, { "source": "Polls", "target": "投票" diff --git a/docs/cli/index.md b/docs/cli/index.md index cd75cd9c8cc..8677f37fa1f 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -37,6 +37,7 @@ This page describes the current CLI behavior. If commands change, update this do - [`models`](/cli/models) - [`infer`](/cli/infer) - [`memory`](/cli/memory) +- [`wiki`](/cli/wiki) - [`directory`](/cli/directory) - [`nodes`](/cli/nodes) - [`devices`](/cli/devices) @@ -162,6 +163,19 @@ openclaw [--dev] [--profile ] status index search + wiki + status + doctor + init + ingest + compile + lint + search + get + apply + bridge import + unsafe-local import + obsidian status|search|open|command|daily message send broadcast diff --git a/docs/cli/memory.md b/docs/cli/memory.md index 51316772b18..0815b455d43 100644 --- a/docs/cli/memory.md +++ b/docs/cli/memory.md @@ -15,6 +15,8 @@ Provided by the active memory plugin (default: `memory-core`; set `plugins.slots Related: - Memory concept: [Memory](/concepts/memory) +- Memory wiki: [Memory Wiki](/plugins/memory-wiki) +- Wiki CLI: [wiki](/cli/wiki) - Plugins: [Plugins](/tools/plugin) ## Examples diff --git a/docs/cli/wiki.md b/docs/cli/wiki.md new file mode 100644 index 00000000000..8259be5f61f --- /dev/null +++ b/docs/cli/wiki.md @@ -0,0 +1,214 @@ +--- +summary: "CLI reference for `openclaw wiki` (memory-wiki vault status, search, compile, lint, apply, bridge, and Obsidian helpers)" +read_when: + - You want to use the memory-wiki CLI + - You are documenting or changing `openclaw wiki` +title: "wiki" +--- + +# `openclaw wiki` + +Inspect and maintain the `memory-wiki` vault. + +Provided by the bundled `memory-wiki` plugin. + +Related: + +- [Memory Wiki plugin](/plugins/memory-wiki) +- [Memory Overview](/concepts/memory) +- [CLI: memory](/cli/memory) + +## What it is for + +Use `openclaw wiki` when you want a compiled knowledge vault with: + +- wiki-native search and page reads +- provenance-rich syntheses +- contradiction and freshness reports +- bridge imports from the active memory plugin +- optional Obsidian CLI helpers + +## Common commands + +```bash +openclaw wiki status +openclaw wiki doctor +openclaw wiki init +openclaw wiki ingest ./notes/alpha.md +openclaw wiki compile +openclaw wiki lint +openclaw wiki search "alpha" +openclaw wiki get entity.alpha --from 1 --lines 80 + +openclaw wiki apply synthesis "Alpha Summary" \ + --body "Short synthesis body" \ + --source-id source.alpha + +openclaw wiki apply metadata entity.alpha \ + --source-id source.alpha \ + --status review \ + --question "Still active?" + +openclaw wiki bridge import +openclaw wiki unsafe-local import + +openclaw wiki obsidian status +openclaw wiki obsidian search "alpha" +openclaw wiki obsidian open syntheses/alpha-summary.md +openclaw wiki obsidian command workspace:quick-switcher +openclaw wiki obsidian daily +``` + +## Commands + +### `wiki status` + +Inspect current vault mode, health, and Obsidian CLI availability. + +Use this first when you are unsure whether the vault is initialized, bridge mode +is healthy, or Obsidian integration is available. + +### `wiki doctor` + +Run wiki health checks and surface configuration or vault problems. + +Typical issues include: + +- bridge mode enabled without public memory artifacts +- invalid or missing vault layout +- missing external Obsidian CLI when Obsidian mode is expected + +### `wiki init` + +Create the wiki vault layout and starter pages. + +This initializes the root structure, including top-level indexes and cache +directories. + +### `wiki ingest ` + +Import content into the wiki source layer. + +Notes: + +- URL ingest is controlled by `ingest.allowUrlIngest` +- imported source pages keep provenance in frontmatter +- auto-compile can run after ingest when enabled + +### `wiki compile` + +Rebuild indexes, related blocks, dashboards, and compiled digests. + +This writes stable machine-facing artifacts under: + +- `.openclaw-wiki/cache/agent-digest.json` +- `.openclaw-wiki/cache/claims.jsonl` + +If `render.createDashboards` is enabled, compile also refreshes report pages. + +### `wiki lint` + +Lint the vault and report: + +- structural issues +- provenance gaps +- contradictions +- open questions +- low-confidence pages/claims +- stale pages/claims + +Run this after meaningful wiki updates. + +### `wiki search ` + +Search wiki content. + +Behavior depends on config: + +- `search.backend`: `shared` or `local` +- `search.corpus`: `wiki`, `memory`, or `all` + +Use `wiki search` when you want wiki-specific ranking or provenance details. +For one broad shared recall pass, prefer `openclaw memory search` when the +active memory plugin exposes shared search. + +### `wiki get ` + +Read a wiki page by id or relative path. + +Examples: + +```bash +openclaw wiki get entity.alpha +openclaw wiki get syntheses/alpha-summary.md --from 1 --lines 80 +``` + +### `wiki apply` + +Apply narrow mutations without freeform page surgery. + +Supported flows include: + +- create/update a synthesis page +- update page metadata +- attach source ids +- add questions +- add contradictions +- update confidence/status +- write structured claims + +This command exists so the wiki can evolve safely without manually editing +managed blocks. + +### `wiki bridge import` + +Import public memory artifacts from the active memory plugin into bridge-backed +source pages. + +Use this in `bridge` mode when you want the latest exported memory artifacts +pulled into the wiki vault. + +### `wiki unsafe-local import` + +Import from explicitly configured local paths in `unsafe-local` mode. + +This is intentionally experimental and same-machine only. + +### `wiki obsidian ...` + +Obsidian helper commands for vaults running in Obsidian-friendly mode. + +Subcommands: + +- `status` +- `search` +- `open` +- `command` +- `daily` + +These require the official `obsidian` CLI on `PATH` when +`obsidian.useOfficialCli` is enabled. + +## Practical usage guidance + +- Use `wiki search` + `wiki get` when provenance and page identity matter. +- Use `wiki apply` instead of hand-editing managed generated sections. +- Use `wiki lint` before trusting contradictory or low-confidence content. +- Use `wiki compile` after bulk imports or source changes when you want fresh + dashboards and compiled digests immediately. +- Use `wiki bridge import` when bridge mode depends on newly exported memory + artifacts. + +## Configuration tie-ins + +`openclaw wiki` behavior is shaped by: + +- `plugins.entries.memory-wiki.config.vaultMode` +- `plugins.entries.memory-wiki.config.search.backend` +- `plugins.entries.memory-wiki.config.search.corpus` +- `plugins.entries.memory-wiki.config.bridge.*` +- `plugins.entries.memory-wiki.config.obsidian.*` +- `plugins.entries.memory-wiki.config.render.*` +- `plugins.entries.memory-wiki.config.context.includeCompiledDigestPrompt` + +See [Memory Wiki plugin](/plugins/memory-wiki) for the full config model. diff --git a/docs/concepts/memory.md b/docs/concepts/memory.md index ec4cfb446a6..3e3d6c21cba 100644 --- a/docs/concepts/memory.md +++ b/docs/concepts/memory.md @@ -40,6 +40,26 @@ The agent has two tools for working with memory: Both tools are provided by the active memory plugin (default: `memory-core`). +## Memory Wiki companion plugin + +If you want durable memory to behave more like a maintained knowledge base than +just raw notes, use the bundled `memory-wiki` plugin. + +`memory-wiki` compiles durable knowledge into a wiki vault with: + +- deterministic page structure +- structured claims and evidence +- contradiction and freshness tracking +- generated dashboards +- compiled digests for agent/runtime consumers +- wiki-native tools like `wiki_search`, `wiki_get`, `wiki_apply`, and `wiki_lint` + +It does not replace the active memory plugin. The active memory plugin still +owns recall, promotion, and dreaming. `memory-wiki` adds a provenance-rich +knowledge layer beside it. + +See [Memory Wiki](/plugins/memory-wiki). + ## Memory search When an embedding provider is configured, `memory_search` uses **hybrid @@ -73,6 +93,15 @@ multi-agent awareness. Plugin install. +## Knowledge wiki layer + + + +Compiles durable memory into a provenance-rich wiki vault with claims, +dashboards, bridge mode, and Obsidian-friendly workflows. + + + ## Automatic memory flush Before [compaction](/concepts/compaction) summarizes your conversation, OpenClaw @@ -117,6 +146,7 @@ openclaw memory index --force # Rebuild the index - [Builtin Memory Engine](/concepts/memory-builtin) -- default SQLite backend - [QMD Memory Engine](/concepts/memory-qmd) -- advanced local-first sidecar - [Honcho Memory](/concepts/memory-honcho) -- AI-native cross-session memory +- [Memory Wiki](/plugins/memory-wiki) -- compiled knowledge vault and wiki-native tools - [Memory Search](/concepts/memory-search) -- search pipeline, providers, and tuning - [Dreaming (experimental)](/concepts/dreaming) -- background promotion diff --git a/docs/plugins/memory-wiki.md b/docs/plugins/memory-wiki.md new file mode 100644 index 00000000000..01b31a40251 --- /dev/null +++ b/docs/plugins/memory-wiki.md @@ -0,0 +1,357 @@ +--- +summary: "memory-wiki: compiled knowledge vault with provenance, claims, dashboards, and bridge mode" +read_when: + - You want persistent knowledge beyond plain MEMORY.md notes + - You are configuring the bundled memory-wiki plugin + - You want to understand wiki_search, wiki_get, or bridge mode +title: "Memory Wiki" +--- + +# Memory Wiki + +`memory-wiki` is a bundled plugin that turns durable memory into a compiled +knowledge vault. + +It does **not** replace the active memory plugin. The active memory plugin still +owns recall, promotion, indexing, and dreaming. `memory-wiki` sits beside it +and compiles durable knowledge into a navigable wiki with deterministic pages, +structured claims, provenance, dashboards, and machine-readable digests. + +Use it when you want memory to behave more like a maintained knowledge layer and +less like a pile of Markdown files. + +## What it adds + +- A dedicated wiki vault with deterministic page layout +- Structured claim and evidence metadata, not just prose +- Page-level provenance, confidence, contradictions, and open questions +- Compiled digests for agent/runtime consumers +- Wiki-native search/get/apply/lint tools +- Optional bridge mode that imports public artifacts from the active memory plugin +- Optional Obsidian-friendly render mode and CLI integration + +## How it fits with memory + +Think of the split like this: + +| Layer | Owns | +| ------------------------------------------------------- | ------------------------------------------------------------------------------------------ | +| Active memory plugin (`memory-core`, QMD, Honcho, etc.) | Recall, semantic search, promotion, dreaming, memory runtime | +| `memory-wiki` | Compiled wiki pages, provenance-rich syntheses, dashboards, wiki-specific search/get/apply | + +If the active memory plugin exposes shared recall artifacts, OpenClaw can search +both layers in one pass with `memory_search corpus=all`. + +When you need wiki-specific ranking, provenance, or direct page access, use the +wiki-native tools instead. + +## Vault modes + +`memory-wiki` supports three vault modes: + +### `isolated` + +Own vault, own sources, no dependency on `memory-core`. + +Use this when you want the wiki to be its own curated knowledge store. + +### `bridge` + +Reads public memory artifacts and memory events from the active memory plugin +through public plugin SDK seams. + +Use this when you want the wiki to compile and organize the memory plugin's +exported artifacts without reaching into private plugin internals. + +Bridge mode can index: + +- exported memory artifacts +- dream reports +- daily notes +- memory root files +- memory event logs + +### `unsafe-local` + +Explicit same-machine escape hatch for local private paths. + +This mode is intentionally experimental and non-portable. Use it only when you +understand the trust boundary and specifically need local filesystem access that +bridge mode cannot provide. + +## Vault layout + +The plugin initializes a vault like this: + +```text +/ + AGENTS.md + WIKI.md + index.md + inbox.md + entities/ + concepts/ + syntheses/ + sources/ + reports/ + _attachments/ + _views/ + .openclaw-wiki/ +``` + +Managed content stays inside generated blocks. Human note blocks are preserved. + +The main page groups are: + +- `sources/` for imported raw material and bridge-backed pages +- `entities/` for durable things, people, systems, projects, and objects +- `concepts/` for ideas, abstractions, patterns, and policies +- `syntheses/` for compiled summaries and maintained rollups +- `reports/` for generated dashboards + +## Structured claims and evidence + +Pages can carry structured `claims` frontmatter, not just freeform text. + +Each claim can include: + +- `id` +- `text` +- `status` +- `confidence` +- `evidence[]` +- `updatedAt` + +Evidence entries can include: + +- `sourceId` +- `path` +- `lines` +- `weight` +- `note` +- `updatedAt` + +This is what makes the wiki act more like a belief layer than a passive note +dump. Claims can be tracked, scored, contested, and resolved back to sources. + +## Compile pipeline + +The compile step reads wiki pages, normalizes summaries, and emits stable +machine-facing artifacts under: + +- `.openclaw-wiki/cache/agent-digest.json` +- `.openclaw-wiki/cache/claims.jsonl` + +These digests exist so agents and runtime code do not have to scrape Markdown +pages. + +Compiled output also powers: + +- first-pass wiki indexing for search/get flows +- claim-id lookup back to owning pages +- compact prompt supplements +- report/dashboard generation + +## Dashboards and health reports + +When `render.createDashboards` is enabled, compile maintains dashboards under +`reports/`. + +Built-in reports include: + +- `reports/open-questions.md` +- `reports/contradictions.md` +- `reports/low-confidence.md` +- `reports/claim-health.md` +- `reports/stale-pages.md` + +These reports track things like: + +- contradiction note clusters +- competing claim clusters +- claims missing structured evidence +- low-confidence pages and claims +- stale or unknown freshness +- pages with unresolved questions + +## Search and retrieval + +`memory-wiki` supports two search backends: + +- `shared`: use the shared memory search flow when available +- `local`: search the wiki locally + +It also supports three corpora: + +- `wiki` +- `memory` +- `all` + +Important behavior: + +- `wiki_search` and `wiki_get` use compiled digests as a first pass when possible +- claim ids can resolve back to the owning page +- contested/stale/fresh claims influence ranking +- provenance labels can survive into results + +Practical rule: + +- use `memory_search corpus=all` for one broad recall pass +- use `wiki_search` + `wiki_get` when you care about wiki-specific ranking, + provenance, or page-level belief structure + +## Agent tools + +The plugin registers these tools: + +- `wiki_status` +- `wiki_search` +- `wiki_get` +- `wiki_apply` +- `wiki_lint` + +What they do: + +- `wiki_status`: current vault mode, health, Obsidian CLI availability +- `wiki_search`: search wiki pages and, when configured, shared memory corpora +- `wiki_get`: read a wiki page by id/path or fall back to shared memory corpus +- `wiki_apply`: narrow synthesis/metadata mutations without freeform page surgery +- `wiki_lint`: structural checks, provenance gaps, contradictions, open questions + +The plugin also registers a non-exclusive memory corpus supplement, so shared +`memory_search` and `memory_get` can reach the wiki when the active memory +plugin supports corpus selection. + +## Prompt and context behavior + +When `context.includeCompiledDigestPrompt` is enabled, memory prompt sections +append a compact compiled snapshot from `agent-digest.json`. + +That snapshot is intentionally small and high-signal: + +- top pages only +- top claims only +- contradiction count +- question count +- confidence/freshness qualifiers + +This is opt-in because it changes prompt shape and is mainly useful for context +engines or legacy prompt assembly that explicitly consume memory supplements. + +## Configuration + +Put config under `plugins.entries.memory-wiki.config`: + +```json5 +{ + plugins: { + entries: { + "memory-wiki": { + enabled: true, + config: { + vaultMode: "isolated", + vault: { + path: "~/.openclaw/wiki/main", + renderMode: "obsidian", + }, + obsidian: { + enabled: true, + useOfficialCli: true, + vaultName: "OpenClaw Wiki", + openAfterWrites: false, + }, + bridge: { + enabled: false, + readMemoryArtifacts: true, + indexDreamReports: true, + indexDailyNotes: true, + indexMemoryRoot: true, + followMemoryEvents: true, + }, + ingest: { + autoCompile: true, + maxConcurrentJobs: 1, + allowUrlIngest: true, + }, + search: { + backend: "shared", + corpus: "wiki", + }, + context: { + includeCompiledDigestPrompt: false, + }, + render: { + preserveHumanBlocks: true, + createBacklinks: true, + createDashboards: true, + }, + }, + }, + }, + }, +} +``` + +Key toggles: + +- `vaultMode`: `isolated`, `bridge`, `unsafe-local` +- `vault.renderMode`: `native` or `obsidian` +- `bridge.readMemoryArtifacts`: import active memory plugin public artifacts +- `bridge.followMemoryEvents`: include event logs in bridge mode +- `search.backend`: `shared` or `local` +- `search.corpus`: `wiki`, `memory`, or `all` +- `context.includeCompiledDigestPrompt`: append compact digest snapshot to memory prompt sections +- `render.createBacklinks`: generate deterministic related blocks +- `render.createDashboards`: generate dashboard pages + +## CLI + +`memory-wiki` also exposes a top-level CLI surface: + +```bash +openclaw wiki status +openclaw wiki doctor +openclaw wiki init +openclaw wiki ingest ./notes/alpha.md +openclaw wiki compile +openclaw wiki lint +openclaw wiki search "alpha" +openclaw wiki get entity.alpha +openclaw wiki apply synthesis "Alpha Summary" --body "..." --source-id source.alpha +openclaw wiki bridge import +openclaw wiki obsidian status +``` + +See [CLI: wiki](/cli/wiki) for the full command reference. + +## Obsidian support + +When `vault.renderMode` is `obsidian`, the plugin writes Obsidian-friendly +Markdown and can optionally use the official `obsidian` CLI. + +Supported workflows include: + +- status probing +- vault search +- opening a page +- invoking an Obsidian command +- jumping to the daily note + +This is optional. The wiki still works in native mode without Obsidian. + +## Recommended workflow + +1. Keep your active memory plugin for recall/promotion/dreaming. +2. Enable `memory-wiki`. +3. Start with `isolated` mode unless you explicitly want bridge mode. +4. Use `wiki_search` / `wiki_get` when provenance matters. +5. Use `wiki_apply` for narrow syntheses or metadata updates. +6. Run `wiki_lint` after meaningful changes. +7. Turn on dashboards if you want stale/contradiction visibility. + +## Related docs + +- [Memory Overview](/concepts/memory) +- [CLI: memory](/cli/memory) +- [CLI: wiki](/cli/wiki) +- [Plugin SDK overview](/plugins/sdk-overview)