@ks-ai/ksmem

Long-term memory plugin for OpenClaw powered by KsMem.

Auto-recall relevant memories before each agent turn, auto-capture conversations after, and optionally expose ksmem_search / ksmem_store as agent tools — all via MCP JSON-RPC 2.0.

⚠️ Privacy & Data Handling

Read before installing.

This plugin transmits conversation data to an external KsMem server that you configure via baseUrl.

| What is sent | When | Where | |---|---|---| | User message text (last turn) | agent_end — after each successful turn | Your baseUrl KsMem server | | Assistant response text (last turn) | agent_end — after each successful turn | Your baseUrl KsMem server | | Search query (user prompt text) | before_agent_start — before each turn | Your baseUrl KsMem server |

Implications:

• You are responsible for choosing a trustworthy baseUrl endpoint. The plugin sends plaintext conversation fragments to it.
• Conversations are stored persistently in the KsMem service for future recall.
• If autoStore: true (default), every successful agent turn is archived.
• If autoSearch: true (default), the user's prompt is sent as a search query to the memory service.
• The plugin does not collect telemetry, analytics, or usage statistics.
• No data is sent to the plugin author.

To disable all data transmission, set both autoSearch: false and autoStore: false in your plugin config.

Installation

# npm
npm install @ks-ai/ksmem

# pnpm
pnpm add @ks-ai/ksmem

Then register it in your OpenClaw configuration:

{
  "plugins": {
    "slots": {
      "memory": "ksmem"
    },
    "entries": {
      "ksmem": {
        "enabled": true,
        "config": {
          "baseUrl": "https://your-ksmem-instance.example.com",
          "apiKey": "ksmem-xxxxxxxxxxxxxxxx"
        }
      }
    }
  }
}

Configuration

| Field | Type | Default | Description | |---|---|---|---| | baseUrl | string | https://mk.ai.kingsoft.com | KsMem server base URL | | apiKey | string | — | API key with ksmem- prefix. Required. Obtain from your KsMem admin. Supports ${KSMEM_API_KEY} env placeholder. | | sceneIds | string[] | ["_sys_general", "_sys_work_assistant"] | Scene IDs for scoping memories | | topK | integer (≥ 1) | 10 | Max memories returned per recall query | | autoSearch | boolean | true | Auto-recall relevant memories before each agent turn (before_agent_start hook) | | autoStore | boolean | true | Auto-capture last-turn conversation after each successful agent turn (agent_end hook) | | toolSearch | boolean | false | Register ksmem_search agent tool for on-demand memory search | | toolStore | boolean | false | Register ksmem_store agent tool for on-demand memory storage | | verbose | boolean | false | Enable verbose debug logging for all plugin operations |

CLI Commands

All CLI commands are under the openclaw ksmem namespace.

openclaw ksmem setup

Interactive setup wizard that configures all plugin settings. Prompts for:

• API key (required)
• Server URL
• Scene IDs
• Top K
• ksmem_search tool (true/false)
• ksmem_store tool (true/false)
• Verbose logging (true/false)

Writes the configuration to ~/.openclaw/openclaw.json and automatically sets:

• plugins.slots.memory = "ksmem"
• tools.allow includes "ksmem"
• plugins.allow includes "ksmem"
• agents.defaults.compaction.memoryFlush.enabled = false

openclaw ksmem status

Displays current configuration status, including:

• API key source (config or environment)
• Memory slot assignment
• All plugin settings
• tools.allow / plugins.allow health checks

If the plugin is explicitly disabled (enabled: false), shows guidance on how to re-enable it using openclaw plugins enable ksmem.

openclaw ksmem config [list|get|set] [key] [value]

Inspect or update the saved KsMem plugin configuration from the terminal.

openclaw ksmem config list
openclaw ksmem config get topK
openclaw ksmem config set topK 20
openclaw ksmem config set autoSearch true

• list or no action: print all supported config keys
• get <key>: print one config value
• set <key> <value>: update one config value in ~/.openclaw/openclaw.json

openclaw ksmem search <query> [--scene <id>] [--limit <n>]

Search memories from the command line. (Only available when plugin is configured.)

| Argument/Option | Description | Default | |---|---|---| | <query> | Search query text | — (required) | | --scene <id> | Scene ID | First configured scene ID | | --limit <n> | Max results | topK from config |

openclaw ksmem store <text> [--scene <id>]

Store a memory from the command line. (Only available when plugin is configured.)

| Argument/Option | Description | Default | |---|---|---| | <text> | Text to store as memory | — (required) | | --scene <id> | Scene ID | First configured scene ID |

Slash Commands

Slash commands are available in the OpenClaw chat interface.

/ksmem-store <text> [--scene <id>]

Save something to long-term memory.

/ksmem-store My preferred editor is VSCode
/ksmem-store My project deadline is next Friday --scene work

/ksmem-search <query> [--scene <id>] [--limit <n>]

Search your long-term memories.

/ksmem-search favorite programming language
/ksmem-search project status --scene work --limit 5

/ksmem-status

Show the current plugin configuration and test server connectivity.

Note: When the plugin is not configured, all slash commands return a message directing you to run openclaw ksmem setup.

How It Works

Auto-Search (before_agent_start)

1. Extracts text from the user's prompt.
2. Sends a search_memory MCP call to your KsMem server.
3. Injects the top-K results as <relevant-memories> context prepended to the prompt.

Auto-Store (agent_end)

1. Collects the last user + assistant message pair.
2. Sends an add_memory MCP call with the conversation data.
3. On session reset (/new, /reset), sets flush: true to clear the rolling memory buffer.

Agent Tools (optional)

• ksmem_search — Search memories by query string (agent-initiated). Enabled via toolSearch: true.
• ksmem_store — Store arbitrary text as a memory (agent-initiated). Enabled via toolStore: true.

Security Notes

• apiKey is sent as a Bearer token in HTTP Authorization headers to your baseUrl.
• All communication uses HTTPS (you must ensure your baseUrl is HTTPS in production).
• The plugin uses native fetch with a 30-second timeout and AbortController.
• Auth errors (401/403) are suppressed for 60 seconds to avoid log spam.

License

Apache-2.0