openclaw-openviking-plugin 0.1.0

package/README.md

@@ -0,0 +1,101 @@
+# openclaw-openviking-plugin
+
+An [OpenClaw](https://openclaw.ai) plugin that integrates with [OpenViking](https://github.com/volcengine/openviking) for long-term memory.
+
+**Hook-only** — does not register as a context engine. Works alongside LCM or any other context engine without conflict.
+
+## Features
+
+- **autoRecall** — searches OpenViking memories before each prompt and injects relevant context
+- **autoCapture** — commits new conversation messages to OpenViking after each turn for memory extraction
+- **memory_recall** tool — model-triggered memory search
+- **memory_store** tool — model-triggered memory write
+- **memory_forget** tool — model-triggered memory deletion
+
+## Requirements
+
+- OpenClaw gateway
+- OpenViking server running and accessible via HTTP
+
+## Installation
+
+### Using `install.sh` (recommended)
+
+```bash
+git clone https://github.com/liushuangls/openclaw-openviking-plugin
+cd openclaw-openviking-plugin
+./install.sh
+```
+
+The script copies plugin files, installs dependencies, updates `openclaw.json`, and restarts the gateway automatically. Re-running it on an already-installed plugin performs an **update** (syncs files + restarts, config unchanged).
+
+```bash
+# Custom OV server address
+OV_BASE_URL=http://192.168.1.100:1934 ./install.sh
+```
+
+### Manual
+
+Copy the directory to `~/.openclaw/extensions/openclaw-openviking-plugin/`, run `npm install --omit=dev` inside it, then add the plugin to `openclaw.json` (see Configuration below) and restart the gateway.
+
+## Configuration
+
+Add to your `openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "allow": ["openclaw-openviking-plugin"],
+    "entries": {
+      "openclaw-openviking-plugin": {
+        "enabled": true,
+        "config": {
+          "baseUrl": "http://127.0.0.1:1934",
+          "apiKey": "",
+          "autoRecall": true,
+          "autoCapture": true,
+          "recallLimit": 6,
+          "recallScoreThreshold": 0.15,
+          "recallTokenBudget": 2000,
+          "recallMaxContentChars": 500,
+          "commitTokenThreshold": 0
+        }
+      }
+    }
+  }
+}
+```
+
+| Field | Default | Description |
+|---|---|---|
+| `baseUrl` | `http://127.0.0.1:1934` | OpenViking server URL |
+| `apiKey` | `""` | API key (if required) |
+| `autoRecall` | `true` | Inject relevant memories before each prompt |
+| `autoCapture` | `true` | Commit conversation turns to OV after each response |
+| `recallLimit` | `6` | Max memories to inject per turn |
+| `recallScoreThreshold` | `0.15` | Minimum relevance score (0–1) |
+| `recallTokenBudget` | `2000` | Max tokens for injected memory context |
+| `recallMaxContentChars` | `500` | Max characters per memory snippet |
+| `commitTokenThreshold` | `0` | Min tokens in a turn before committing (0 = always) |
+
+## Testing
+
+```bash
+npm install
+
+# Unit tests (no server required)
+npm run test:unit
+
+# Integration tests (requires OV server)
+OV_BASE_URL=http://127.0.0.1:1934 npm run test:integration
+```
+
+Integration tests skip automatically if the server is unreachable.
+
+## Coexistence with LCM
+
+This plugin uses **hooks only** (`before_prompt_build` + `agent_end`). It does not set `kind: "context-engine"` and does not occupy the exclusive context engine slot, so it runs alongside [lossless-claw](https://github.com/martian-engineering/lossless-claw) or any other context engine without conflict.
+
+## License
+
+MIT

package/README_CN.md

@@ -0,0 +1,110 @@
+# openclaw-openviking-plugin
+
+[OpenClaw](https://openclaw.ai) 的长期记忆插件，通过集成 [OpenViking](https://github.com/volcengine/openviking) 实现 AI Agent 的持久化记忆管理。
+
+**Hook-only 设计** — 不注册为 context engine，不占用独占槽位，可与 LCM 或其他 context engine 无冲突共存。
+
+## 功能
+
+- **autoRecall** — 每次对话前自动搜索 OpenViking 记忆，将相关内容注入 prompt
+- **autoCapture** — 每轮对话结束后自动将新增消息提交到 OpenViking，触发记忆提取
+- **memory_recall** 工具 — 模型主动触发记忆搜索
+- **memory_store** 工具 — 模型主动写入记忆
+- **memory_forget** 工具 — 模型主动删除记忆
+
+## 依赖
+
+- OpenClaw gateway
+- OpenViking server（本地或远程，HTTP 可访问）
+
+## 安装
+
+### 使用 `install.sh`（推荐）
+
+```bash
+git clone https://github.com/liushuangls/openclaw-openviking-plugin
+cd openclaw-openviking-plugin
+./install.sh
+```
+
+脚本会自动完成：复制插件文件 → 安装依赖 → 更新 `openclaw.json` → 重启 gateway。
+
+已安装的情况下重复执行为**更新模式**，只同步文件和重启，不覆盖配置。
+
+```bash
+# 指定 OV server 地址
+OV_BASE_URL=http://192.168.1.100:1934 ./install.sh
+```
+
+### 手动安装
+
+将目录复制到 `~/.openclaw/extensions/openclaw-openviking-plugin/`，在目录内执行 `npm install --omit=dev`，然后按下方配置格式更新 `openclaw.json`，重启 gateway 生效。
+
+## 配置
+
+在 `openclaw.json` 中添加：
+
+```json
+{
+  "plugins": {
+    "allow": ["openclaw-openviking-plugin"],
+    "entries": {
+      "openclaw-openviking-plugin": {
+        "enabled": true,
+        "config": {
+          "baseUrl": "http://127.0.0.1:1934",
+          "apiKey": "",
+          "autoRecall": true,
+          "autoCapture": true,
+          "recallLimit": 6,
+          "recallScoreThreshold": 0.15,
+          "recallTokenBudget": 2000,
+          "recallMaxContentChars": 500,
+          "commitTokenThreshold": 0
+        }
+      }
+    }
+  }
+}
+```
+
+| 字段 | 默认值 | 说明 |
+|---|---|---|
+| `baseUrl` | `http://127.0.0.1:1934` | OpenViking server 地址 |
+| `apiKey` | `""` | API Key（按需填写） |
+| `autoRecall` | `true` | 每次 prompt 前自动召回相关记忆 |
+| `autoCapture` | `true` | 每轮对话结束后自动提交并提取记忆 |
+| `recallLimit` | `6` | 单次最多注入的记忆条数 |
+| `recallScoreThreshold` | `0.15` | 最低相关性分数（0–1） |
+| `recallTokenBudget` | `2000` | 注入记忆的最大 token 数 |
+| `recallMaxContentChars` | `500` | 单条记忆最大字符数 |
+| `commitTokenThreshold` | `0` | 提交记忆的最低 token 阈值（0 = 每轮都提交） |
+
+## 测试
+
+```bash
+npm install
+
+# 单元测试（不需要 OV server）
+npm run test:unit
+
+# 集成测试（需要 OV server 运行中）
+OV_BASE_URL=http://127.0.0.1:1934 npm run test:integration
+```
+
+OV server 不可达时集成测试自动跳过。
+
+## 与 LCM 共存
+
+本插件只使用 hook（`before_prompt_build` + `agent_end`），不设置 `kind: "context-engine"`，不占用独占的 context engine 槽位，可与 [lossless-claw](https://github.com/martian-engineering/lossless-claw) 等插件同时运行。
+
+- **LCM** 负责对话压缩与上下文管理
+- **OpenViking 插件** 负责跨 session 的长期记忆自动捕获与召回
+
+## 升级注意事项
+
+升级 OpenViking server 前，建议先对比官方插件 `client.ts` 是否有变更，有则同步后跑一次集成测试再升级。最敏感的接口是 `fs/ls` 和 `system/status`（URI 归一化依赖这两个）。
+
+## License
+
+MIT

package/client.ts

@@ -0,0 +1,381 @@
+import { createHash } from "node:crypto";
+
+export type FindResultItem = {
+  uri: string;
+  level?: number;
+  abstract?: string;
+  overview?: string;
+  category?: string;
+  score?: number;
+  match_reason?: string;
+};
+
+export type FindResult = {
+  memories?: FindResultItem[];
+  resources?: FindResultItem[];
+  skills?: FindResultItem[];
+  total?: number;
+};
+
+export type CommitSessionResult = {
+  session_id: string;
+  status: string;
+  task_id?: string;
+  archive_uri?: string;
+  archived?: boolean;
+  memories_extracted?: Record<string, number>;
+  error?: string;
+};
+
+export type TaskResult = {
+  status: string;
+  result?: unknown;
+  error?: string;
+};
+
+type ScopeName = "user" | "agent";
+type RuntimeIdentity = { userId: string; agentId: string };
+
+export class OpenVikingRequestError extends Error {
+  readonly status: number;
+  readonly code?: string;
+
+  constructor(status: number, message: string, code?: string) {
+    super(
+      `OpenViking request failed (status ${status}${code ? `, code ${code}` : ""}): ${message}`,
+    );
+    this.name = "OpenVikingRequestError";
+    this.status = status;
+    this.code = code;
+  }
+}
+
+type CommitSessionOptions = {
+  wait?: boolean;
+  timeoutMs?: number;
+  agentId?: string;
+};
+
+type OpenVikingClientOptions = {
+  baseUrl: string;
+  apiKey?: string;
+  agentId?: string;
+  timeoutMs?: number;
+};
+
+const USER_STRUCTURE_DIRS = new Set(["memories"]);
+const AGENT_STRUCTURE_DIRS = new Set(["memories", "skills", "instructions", "workspaces"]);
+
+function md5Short(input: string): string {
+  return createHash("md5").update(input).digest("hex").slice(0, 12);
+}
+
+export class OpenVikingClient {
+  private readonly baseUrl: string;
+  private readonly apiKey: string;
+  private readonly defaultAgentId: string;
+  private readonly timeoutMs: number;
+  private spaceCache = new Map<string, Partial<Record<ScopeName, string>>>();
+  private identityCache = new Map<string, RuntimeIdentity>();
+
+  constructor(options: OpenVikingClientOptions) {
+    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.apiKey = options.apiKey?.trim() ?? "";
+    this.defaultAgentId = options.agentId?.trim() ?? "";
+    this.timeoutMs = options.timeoutMs ?? 15_000;
+  }
+
+  async find(
+    query: string,
+    targetUri: string,
+    limit: number,
+    scoreThreshold = 0,
+    agentId?: string,
+  ): Promise<FindResult> {
+    const normalizedUri = await this.normalizeTargetUri(targetUri, agentId);
+
+    return this.request<FindResult>(
+      "/api/v1/search/find",
+      {
+        method: "POST",
+        body: JSON.stringify({
+          query,
+          target_uri: normalizedUri,
+          limit,
+          score_threshold: scoreThreshold,
+        }),
+      },
+      agentId,
+    );
+  }
+
+  private async ls(uri: string, agentId?: string): Promise<Array<Record<string, unknown>>> {
+    return this.request<Array<Record<string, unknown>>>(
+      `/api/v1/fs/ls?uri=${encodeURIComponent(uri)}&output=original`,
+      { method: "GET" },
+      agentId,
+    );
+  }
+
+  private async getRuntimeIdentity(agentId?: string): Promise<RuntimeIdentity> {
+    const effectiveAgentId = agentId?.trim() || this.defaultAgentId;
+    const cached = this.identityCache.get(effectiveAgentId);
+    if (cached) {
+      return cached;
+    }
+
+    const fallback: RuntimeIdentity = {
+      userId: "default",
+      agentId: effectiveAgentId || "default",
+    };
+
+    try {
+      const status = await this.request<{ user?: unknown }>(
+        "/api/v1/system/status",
+        { method: "GET" },
+        agentId,
+      );
+      const userId =
+        typeof status.user === "string" && status.user.trim() ? status.user.trim() : "default";
+      const identity: RuntimeIdentity = { userId, agentId: effectiveAgentId || "default" };
+      this.identityCache.set(effectiveAgentId, identity);
+      return identity;
+    } catch {
+      this.identityCache.set(effectiveAgentId, fallback);
+      return fallback;
+    }
+  }
+
+  private async resolveScopeSpace(scope: ScopeName, agentId?: string): Promise<string> {
+    const effectiveAgentId = agentId?.trim() || this.defaultAgentId;
+    const agentScopes = this.spaceCache.get(effectiveAgentId);
+    const cached = agentScopes?.[scope];
+    if (cached) {
+      return cached;
+    }
+
+    const identity = await this.getRuntimeIdentity(agentId);
+    const fallbackSpace =
+      scope === "user" ? identity.userId : md5Short(`${identity.userId}:${identity.agentId}`);
+    const reservedDirs = scope === "user" ? USER_STRUCTURE_DIRS : AGENT_STRUCTURE_DIRS;
+    const preferredSpace =
+      scope === "user" ? identity.userId : md5Short(`${identity.userId}:${identity.agentId}`);
+
+    const saveSpace = (space: string) => {
+      const existing = this.spaceCache.get(effectiveAgentId) ?? {};
+      existing[scope] = space;
+      this.spaceCache.set(effectiveAgentId, existing);
+    };
+
+    try {
+      const entries = await this.ls(`viking://${scope}`, agentId);
+      const spaces = entries
+        .filter((entry) => entry?.isDir === true)
+        .map((entry) => (typeof entry.name === "string" ? entry.name.trim() : ""))
+        .filter((name) => name && !name.startsWith(".") && !reservedDirs.has(name));
+
+      if (spaces.length > 0) {
+        if (spaces.includes(preferredSpace)) {
+          saveSpace(preferredSpace);
+          return preferredSpace;
+        }
+        if (scope === "user" && spaces.includes("default")) {
+          saveSpace("default");
+          return "default";
+        }
+        if (spaces.length === 1) {
+          saveSpace(spaces[0]!);
+          return spaces[0]!;
+        }
+      }
+    } catch {
+      // Fall back to identity-derived space when listing fails.
+    }
+
+    saveSpace(fallbackSpace);
+    return fallbackSpace;
+  }
+
+  private async normalizeTargetUri(targetUri: string, agentId?: string): Promise<string> {
+    const trimmed = targetUri.trim().replace(/\/+$/, "");
+    const match = trimmed.match(/^viking:\/\/(user|agent)(?:\/(.*))?$/);
+    if (!match) {
+      return trimmed;
+    }
+
+    const scope = match[1] as ScopeName;
+    const rawRest = (match[2] ?? "").trim();
+    if (!rawRest) {
+      return trimmed;
+    }
+
+    const parts = rawRest.split("/").filter(Boolean);
+    if (parts.length === 0) {
+      return trimmed;
+    }
+
+    const reservedDirs = scope === "user" ? USER_STRUCTURE_DIRS : AGENT_STRUCTURE_DIRS;
+    if (!reservedDirs.has(parts[0]!)) {
+      return trimmed;
+    }
+
+    const space = await this.resolveScopeSpace(scope, agentId);
+    return `viking://${scope}/${space}/${parts.join("/")}`;
+  }
+
+  async read(uri: string, agentId?: string): Promise<string> {
+    try {
+      return await this.request<string>(
+        `/api/v1/content/read?uri=${encodeURIComponent(uri)}`,
+        { method: "GET" },
+        agentId,
+      );
+    } catch (error) {
+      if (error instanceof OpenVikingRequestError && error.status === 404) {
+        return "";
+      }
+      throw error;
+    }
+  }
+
+  async addSessionMessage(
+    sessionId: string,
+    role: string,
+    content: string,
+    agentId?: string,
+  ): Promise<void> {
+    await this.request<{ session_id: string }>(
+      `/api/v1/sessions/${encodeURIComponent(sessionId)}/messages`,
+      {
+        method: "POST",
+        body: JSON.stringify({ role, content }),
+      },
+      agentId,
+    );
+  }
+
+  async commitSession(
+    sessionId: string,
+    optionsOrAgentId?: string | CommitSessionOptions,
+  ): Promise<CommitSessionResult> {
+    const options: CommitSessionOptions =
+      typeof optionsOrAgentId === "string"
+        ? { agentId: optionsOrAgentId }
+        : (optionsOrAgentId ?? {});
+
+    const result = await this.request<CommitSessionResult>(
+      `/api/v1/sessions/${encodeURIComponent(sessionId)}/commit`,
+      {
+        method: "POST",
+        body: JSON.stringify({}),
+      },
+      options.agentId,
+    );
+
+    if (!options.wait || !result.task_id) {
+      return result;
+    }
+
+    const deadline = Date.now() + (options.timeoutMs ?? 120_000);
+    while (Date.now() < deadline) {
+      await sleep(500);
+      const task = await this.getTask(result.task_id, options.agentId).catch(() => null);
+      if (!task) {
+        break;
+      }
+      if (task.status === "completed") {
+        const taskResult =
+          task.result && typeof task.result === "object"
+            ? (task.result as Record<string, unknown>)
+            : {};
+        result.status = "completed";
+        result.memories_extracted = (taskResult.memories_extracted ??
+          {}) as Record<string, number>;
+        return result;
+      }
+      if (task.status === "failed") {
+        result.status = "failed";
+        result.error = task.error;
+        return result;
+      }
+    }
+
+    result.status = "timeout";
+    return result;
+  }
+
+  async getTask(taskId: string, agentId?: string): Promise<TaskResult> {
+    return this.request<TaskResult>(
+      `/api/v1/tasks/${encodeURIComponent(taskId)}`,
+      { method: "GET" },
+      agentId,
+    );
+  }
+
+  async delete(uri: string, agentId?: string): Promise<void> {
+    try {
+      await this.request<void>(
+        `/api/v1/fs/delete?uri=${encodeURIComponent(uri)}`,
+        { method: "DELETE" },
+        agentId,
+      );
+    } catch (error) {
+      if (error instanceof OpenVikingRequestError && error.status === 404) {
+        return;
+      }
+      throw error;
+    }
+  }
+
+  private async request<T>(path: string, init: RequestInit, agentId?: string): Promise<T> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+
+    try {
+      const headers = new Headers(init.headers ?? {});
+      if (this.apiKey) {
+        headers.set("X-Api-Key", this.apiKey);
+      }
+
+      const effectiveAgentId = agentId?.trim() || this.defaultAgentId;
+      if (effectiveAgentId) {
+        headers.set("X-OpenViking-Agent", effectiveAgentId);
+      }
+
+      if (init.body && !headers.has("Content-Type")) {
+        headers.set("Content-Type", "application/json");
+      }
+
+      const response = await fetch(`${this.baseUrl}${path}`, {
+        ...init,
+        headers,
+        signal: controller.signal,
+      });
+
+      const payload = (await response.json().catch(() => undefined)) as
+        | {
+            status?: string;
+            result?: T;
+            error?: { code?: string; message?: string };
+          }
+        | undefined;
+
+      if (!response.ok || payload?.status === "error") {
+        const code = payload?.error?.code;
+        const message =
+          payload?.error?.message ??
+          response.statusText ??
+          `HTTP ${response.status}`;
+        throw new OpenVikingRequestError(response.status, message, code);
+      }
+
+      return (payload?.result ?? payload) as T;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}