@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 expose memory_search / memory_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 autoCapture: true (default), every successful agent turn is archived.
• If autoRecall: 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 autoRecall: false and autoCapture: 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 | Required | Type | Default | Description | |---|---|---|---|---| | baseUrl | Yes | string | — | KsMem server base URL. Must be provided — no default is shipped. | | apiKey | Yes | string | — | API key with ksmem- prefix. Obtain from your KsMem admin. | | sceneId | No | string | _sys_general | Scene / context identifier for scoping memories. | | topK | No | integer ≥ 1 | 20 | Max memories returned per recall query. | | autoRecall | No | boolean | true | Inject relevant memories before each agent turn. | | autoCapture | No | boolean | true | Archive last-turn conversation after each successful turn. |

How It Works

Auto-Recall (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-Capture (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

• memory_search — Search memories by query string (agent-initiated).
• memory_store — Store arbitrary text as a memory (agent-initiated).

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