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: In assemble(), automatically searches for relevant memories and prepends them to the current user message 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-server

The 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 openviking

Restart 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