mirror of
https://github.com/moltbot/moltbot.git
synced 2026-04-23 14:45:46 +00:00
docs: add memory wiki docs
This commit is contained in:
Peter Steinberger
357
docs/plugins/memory-wiki.md
Normal file
357
docs/plugins/memory-wiki.md
Normal file
@@ -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
|
||||
<vault>/
|
||||
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)
|
||||
Reference in New Issue
Block a user