OpenViking Memory Guide
How It Works
- Auto-Capture: At
afterTurn(end of one user turn run), automatically extracts memories from user/assistant messages
- semantic mode: captures all qualifying user text, relying on OpenViking's extraction pipeline to filter - keyword mode: only captures text matching trigger words (e.g. "remember", "preference", etc.)
- Auto-Recall: At
before_prompt_build, automatically searches for relevant memories and injects them into context
Available Tools
memory_recall — Search Memories
Searches long-term memories in OpenViking, returns relevant results.
| Parameter | Required | Description |
|---|---|---|
query | Yes | Search query text |
limit | No | Maximum number of results (defaults to plugin config) |
scoreThreshold | No | Minimum relevance score 0-1 (defaults to plugin config) |
targetUri | No | Search scope URI (defaults to plugin config) |
Example: User asks "What programming language did I say I like?"
memory_store — Manual Store
Writes text to an OpenViking session and runs memory extraction.
| Parameter | Required | Description |
|---|---|---|
text | Yes | Information text to store |
role | No | Session role (default user) |
sessionId | No | Existing OpenViking session ID |
Example: User says "Remember my email is xxx@example.com"
memory_forget — Delete Memories
Delete by exact URI, or search and delete.
| Parameter | Required | Description |
|---|---|---|
uri | No | Exact memory URI (direct delete) |
query | No | Search query (find then delete) |
targetUri | No | Search scope URI |
limit | No | Search limit (default 5) |
scoreThreshold | No | Minimum relevance score |
Example: User says "Forget my phone number"
Configuration
The plugin connects to an OpenViking HTTP server. Start OpenViking first and keep it running:
openviking-server init
openviking-server doctor
openviking-serverThe default local plugin URL is http://127.0.0.1:1933. Check it with:
curl http://127.0.0.1:1933/health| Field | Default | Description |
|---|---|---|
baseUrl | http://127.0.0.1:1933 | OpenViking server URL |
apiKey | — | OpenViking API Key (optional) |
agent_prefix | empty | Optional prefix for OpenClaw agent IDs. Interactive setup accepts only letters, digits, _, and -. If no agent ID is available, the plugin uses main |
targetUri | viking://user/memories | Default search scope |
autoCapture | true | Automatically capture memories |
captureMode | semantic | Capture mode: semantic / keyword |
captureMaxLength | 24000 | Maximum text length per capture |
autoRecall | true | Automatically recall and inject context |
recallLimit | 6 | Maximum memories injected during auto-recall |
recallScoreThreshold | 0.01 | Minimum relevance score for recall |
Daily Operations
# Start OpenViking server
openviking-server
# Start or restart OpenClaw gateway
openclaw gateway
# Check status
openclaw status
openclaw config get plugins.slots.contextEngine
# Disable memory
openclaw config set plugins.slots.contextEngine legacy
# Enable memory
openclaw config set plugins.slots.contextEngine openvikingRestart the gateway after changing the slot.
Multi-Instance Support
If you have multiple OpenClaw instances, use --workdir to target a specific one:
# Setup helper
npx ./examples/openclaw-plugin/setup-helper --workdir ~/.openclaw-openclaw-second
# Manual config (prefix openclaw commands)
OPENCLAW_STATE_DIR=~/.openclaw-openclaw-second openclaw config set ...Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
extracted 0 memories | Wrong API Key or model name | Check server-side VLM and embedding configuration |
| Cannot connect to OpenViking | baseUrl is wrong or service is down | Verify baseUrl and test connectivity |
| Plugin not loaded | Slot not configured | Check openclaw status output |
| Inaccurate recall | recallScoreThreshold too low | Increase threshold or adjust recallLimit |