Keyoku

Configuration

All plugin settings live in your openclaw.json file under the keyoku-memory entry in plugins.entries. Every parameter has a sensible default — most installations work out of the box.

Example config

A typical openclaw.json configuration block with commonly adjusted values.

{
  "plugins": {
    "entries": {
      "keyoku-memory": {
        "enabled": true,
        "config": {
          "keyokuUrl": "http://localhost:18900",
          "autoRecall": true,
          "autoCapture": true,
          "heartbeat": true,
          "incrementalCapture": true,
          "topK": 5,
          "autonomy": "suggest",
          "entityId": "",
          "agentId": "",
          "entityStrategy": "static",
          "entityTemplate": "{base}",
          "captureInGroups": true,
          "recallInGroups": true,
          "captureMaxChars": 2000
        }
      }
    },
    "slots": {
      "memory": "keyoku-memory"
    }
  }
}

Parameter reference

Every configurable parameter, its type, default value, and behavior.

default: "http://localhost:18900"

keyokuUrl

Base URL for the Keyoku Engine API.

Change this if you run the engine on a different port or host.

string
default: true

autoRecall

Searches memories before every response and injects them into the prompt.

When enabled, the plugin injects matching memories as a <your-memories> block in the prompt context.

boolean
default: true

autoCapture

Extracts structured facts from every user-agent exchange.

Sends each exchange to the engine for memory extraction automatically.

boolean
default: true

heartbeat

Intercepts OpenClaw heartbeat prompts for a 14-signal proactive scan.

When enabled, the plugin calls the engine for proactive signal detection on each heartbeat tick.

boolean
default: true

incrementalCapture

Capture memories per-message instead of at session end.

Incremental capture is recommended for real-time conversations. Set to false for batch capture at session end.

boolean
default: 5

topK

Number of memories to inject per prompt during auto-recall.

Higher values give the LLM more context but increase token usage.

number
default: "suggest"

autonomy

Controls how the agent acts on heartbeat signals.

"observe" collects silently, "suggest" surfaces suggestions to the user, "act" executes automatically when policy allows.

"observe" | "suggest" | "act"
default: ""

entityId

Base memory namespace for storing memories.

All memories are stored under this entity ID unless entityStrategy overrides it.

string
default: ""

agentId

Attribution marker identifying which agent created a memory.

Useful when multiple agents share the same entity namespace.

string
default: "static"

entityStrategy

How entity IDs are resolved at runtime.

"static" uses entityId as-is. "per-user" creates a namespace per sender. "per-channel" per channel. "per-session" per session. "template" uses entityTemplate.

"static" | "per-user" | "per-channel" | "per-session" | "template"
default: "{base}"

entityTemplate

Template string used when entityStrategy is "template".

Supports placeholders: {base}, {provider}, {channel}, {chatType}, {senderId}, {chatId}, {sessionKey}. Example: "{base}:{provider}:{senderId}".

string
default: true

captureInGroups

Allow auto-capture in group chat contexts.

Set to false to disable memory extraction in group conversations.

boolean
default: true

recallInGroups

Allow auto-recall in group chat contexts.

Set to false to prevent memory injection in group conversations.

boolean
default: 2000

captureMaxChars

Maximum character length for the combined user+agent exchange sent to capture.

Longer exchanges are truncated to this limit before being sent to the capture endpoint.

number

Entity strategies

The entityStrategy parameter controls how the plugin resolves entity IDs at runtime. This determines memory isolation boundaries.

static

Uses the value of entityId as-is.

Best for single-user agents and personal assistants.

per-user

Creates a namespace per sender.

Resolves to {entityId}:user:{provider}:{senderId}. Best for multi-user bots with separate memory per person.

per-channel

Creates a namespace per channel.

Resolves to {entityId}:channel:{provider}:{chatId}. Best for channel-specific memory like project channels.

per-session

Creates a namespace per session.

Resolves to {entityId}:session:{sessionKey}. Ephemeral memory that resets per session.

template

Uses the evaluated entityTemplate string.

Custom isolation logic using placeholders like {base}, {provider}, {senderId}.

Related

See Installation for setup, or Hooks & Tools for how these settings affect runtime behavior.