npm package: @ks-ai/ksmem
Description: KsMem long-term memory plugin for OpenClaw — auto-recall, auto-capture, and agent tools via MCP JSON-RPC
Latest version: 0.1.5

# @ks-ai/ksmem

Long-term memory plugin for [OpenClaw](https://openclaw.ai) 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

```bash
# npm
npm install @ks-ai/ksmem

# pnpm
pnpm add @ks-ai/ksmem
```

Then register it in your OpenClaw configuration:

```json
{
  "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](https://www.apache.org/licenses/LICENSE-2.0)