claude-code-openviking 0.2.0

package/README.md

@@ -0,0 +1,185 @@
+# openviking-claude-code
+
+**OpenViking long-term memory integration for Claude Code.**
+
+> Give Claude Code persistent memory across sessions — auto-recall past context, auto-capture new learnings.
+
+[English](#english) | [中文](#中文)
+
+---
+
+<a name="english"></a>
+
+## English
+
+### What is this?
+
+`openviking-claude-code` connects Claude Code to an [OpenViking](https://github.com/volcengine/OpenViking) server for long-term memory. Once installed:
+
+- **Auto-recall**: Every message triggers a memory search — relevant past context is injected automatically
+- **Auto-capture**: Every Claude response is silently sent to OpenViking for memory extraction
+- **MCP tools**: `memory_recall`, `memory_store`, `memory_forget` available for manual use
+
+### v0.2.0 — Tiered Memory
+
+The recall system now leverages OpenViking's native L0/L1/L2 context layers:
+
+- **Split-space search** — Searches user preferences and agent experience memories separately, then merges results. Ensures both types surface.
+- **L0/L1 tiered injection** — Top-3 highest-scoring memories inject L1 overview (~300 tokens each) for rich context. Remaining memories inject L0 abstract (~50 tokens each) for broad coverage.
+- **3x coverage** — Same 2000-token budget now covers ~20 memories instead of 6.
+- **Smart capture filtering** — Trivial conversations (< 2 turns or very short responses) are skipped, reducing noise in stored memories.
+
+### Quick Start
+
+```bash
+npx claude-openviking
+```
+
+You'll be asked for your OpenViking server URL and API key. That's it.
+
+### Non-Interactive
+
+```bash
+npx claude-openviking --url http://your-server:1933 --key your-api-key
+```
+
+### What Gets Installed
+
+| Component | Location | Purpose |
+|---|---|---|
+| `auto-recall.cjs` | `~/.claude/hooks/openviking/` | Search memories on every `UserPromptSubmit` |
+| `auto-capture.cjs` | `~/.claude/hooks/openviking/` | Capture conversation on every `Stop` (async) |
+| `mcp-server.cjs` | `~/.claude/hooks/openviking/` | MCP stdio server for memory tools |
+| Hook config | `~/.claude/settings.json` | Registers hooks with Claude Code |
+| MCP config | `.mcp.json` (current directory) | Registers MCP server |
+
+### How It Works
+
+```
+You send a message
+  ↓
+auto-recall hook fires
+  → searches user memories + agent memories + global (parallel)
+  → merges & deduplicates by URI
+  → top-3 inject L1 overview (rich), rest inject L0 abstract (compact)
+  ↓
+Claude sees your message + tiered memories → responds
+  ↓
+auto-capture hook fires (async)
+  → quality gate: skips if < 2 turns or assistant text < 50 chars
+  → sends conversation to OpenViking for memory extraction
+```
+
+### Configuration
+
+All settings use environment variables (with defaults from setup):
+
+| Variable | Description |
+|---|---|
+| `OPENVIKING_BASE_URL` | OpenViking server URL |
+| `OPENVIKING_API_KEY` | API key for authentication |
+| `OPENVIKING_AGENT_ID` | Agent identifier (default: `claude-code`) |
+
+### MCP Tools
+
+| Tool | Description |
+|---|---|
+| `memory_recall` | Search memories by query |
+| `memory_store` | Store text as memory |
+| `memory_forget` | Delete a memory by URI or search query |
+
+### Uninstall
+
+```bash
+npx claude-openviking --uninstall
+```
+
+Removes hooks and settings entries. MCP config (`.mcp.json`) left for manual cleanup.
+
+### Author
+
+**Bill Zhao** — [LinkedIn](https://www.linkedin.com/in/billzhaodi/) | [GitHub](https://github.com/billzhao9)
+
+### Credits
+
+- [OpenViking](https://github.com/volcengine/OpenViking) — Long-term memory backend
+- [Claude Code](https://claude.com/claude-code) — The AI coding assistant
+
+### License
+
+MIT
+
+---
+
+<a name="中文"></a>
+
+## 中文
+
+### 这是什么？
+
+`openviking-claude-code` 为 Claude Code 接入 [OpenViking](https://github.com/volcengine/OpenViking) 长期记忆服务。安装后：
+
+- **自动召回**：每条消息自动搜索记忆，注入相关上下文
+- **自动捕获**：每次回复后静默发送对话到 OpenViking 提取记忆
+- **MCP 工具**：`memory_recall`、`memory_store`、`memory_forget` 可手动调用
+
+### v0.2.0 — 分层记忆
+
+召回系统现在利用 OpenViking 原生的 L0/L1/L2 上下文分层：
+
+- **分空间搜索** — 分别搜索用户偏好和 agent 经验记忆，合并结果，确保两类记忆都能浮现
+- **L0/L1 分层注入** — 前 3 条高分记忆注入 L1 概要（详细），其余注入 L0 摘要（精简）
+- **3 倍覆盖** — 同样 2000 token 预算，覆盖 ~20 条记忆（之前只有 6 条）
+- **智能捕获过滤** — 跳过过于简短的对话（< 2 轮或回复太短），减少噪音记忆
+
+### 快速安装
+
+```bash
+npx claude-openviking
+```
+
+输入 OpenViking 服务器地址和 API key 即可。
+
+### 非交互安装
+
+```bash
+npx claude-openviking --url http://your-server:1933 --key your-api-key
+```
+
+### 安装了什么
+
+| 组件 | 位置 | 功能 |
+|---|---|---|
+| `auto-recall.cjs` | `~/.claude/hooks/openviking/` | 每条消息自动搜索记忆 |
+| `auto-capture.cjs` | `~/.claude/hooks/openviking/` | 每次回复后异步捕获对话 |
+| `mcp-server.cjs` | `~/.claude/hooks/openviking/` | MCP 工具服务 |
+| Hook 配置 | `~/.claude/settings.json` | 注册 hooks |
+| MCP 配置 | `.mcp.json`（当前目录） | 注册 MCP server |
+
+### 工作流程
+
+```
+你发一条消息
+  ↓
+auto-recall 触发 → 搜索 OpenViking → 注入相关记忆
+  ↓
+Claude 看到你的消息 + 记忆 → 回复
+  ↓
+auto-capture 触发（异步）→ 对话发到 OpenViking
+  ↓
+OpenViking 提取并存储记忆，供未来召回
+```
+
+### 卸载
+
+```bash
+npx claude-openviking --uninstall
+```
+
+### 作者
+
+**Bill Zhao** — [LinkedIn](https://www.linkedin.com/in/billzhaodi/) | [GitHub](https://github.com/billzhao9)
+
+### 协议
+
+MIT

package/bin/setup.cjs

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+/**
+ * claude-openviking setup script
+ *
+ * Installs hooks + MCP server config for Claude Code.
+ * Usage:
+ *   npx claude-openviking                          # interactive setup
+ *   npx claude-openviking --url http://... --key xxx  # non-interactive
+ *   npx claude-openviking --uninstall              # remove
+ */
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const readline = require("readline");
+
+const CLAUDE_DIR = path.join(os.homedir(), ".claude");
+const HOOKS_DIR = path.join(CLAUDE_DIR, "hooks", "openviking");
+const SETTINGS_PATH = path.join(CLAUDE_DIR, "settings.json");
+const PKG_HOOKS_DIR = path.join(__dirname, "..", "hooks");
+
+const args = process.argv.slice(2);
+const isUninstall = args.includes("--uninstall");
+const urlArg = args[args.indexOf("--url") + 1];
+const keyArg = args[args.indexOf("--key") + 1];
+const agentArg = args[args.indexOf("--agent") + 1];
+
+async function ask(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => rl.question(question, (answer) => { rl.close(); resolve(answer.trim()); }));
+}
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeJson(filePath, data) {
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n", "utf8");
+}
+
+// --- Uninstall ---
+
+function uninstall() {
+  console.log("🗑️  Removing claude-openviking...\n");
+
+  // Remove hooks dir
+  if (fs.existsSync(HOOKS_DIR)) {
+    fs.rmSync(HOOKS_DIR, { recursive: true });
+    console.log("  ✅ Removed hooks directory");
+  }
+
+  // Remove hook entries from settings.json
+  const settings = readJson(SETTINGS_PATH);
+  if (settings?.hooks) {
+    let changed = false;
+
+    for (const event of ["UserPromptSubmit", "Stop"]) {
+      if (Array.isArray(settings.hooks[event])) {
+        const before = settings.hooks[event].length;
+        settings.hooks[event] = settings.hooks[event].filter(
+          (entry) => !JSON.stringify(entry).includes("openviking")
+        );
+        if (settings.hooks[event].length === 0) delete settings.hooks[event];
+        if (settings.hooks[event]?.length !== before) changed = true;
+      }
+    }
+
+    if (changed) {
+      writeJson(SETTINGS_PATH, settings);
+      console.log("  ✅ Removed hooks from settings.json");
+    }
+  }
+
+  console.log("\n✅ Uninstalled. MCP server config (.mcp.json) left untouched — remove manually if needed.");
+  process.exit(0);
+}
+
+// --- Install ---
+
+async function install() {
+  console.log("🦞 claude-openviking setup\n");
+  console.log("This will install OpenViking memory integration for Claude Code:\n");
+  console.log("  • Auto-recall: search memories before every message");
+  console.log("  • Auto-capture: save conversation to OpenViking after every reply");
+  console.log("  • MCP tools: memory_recall, memory_store, memory_forget\n");
+
+  // Get config
+  let baseUrl = urlArg;
+  let apiKey = keyArg;
+  let agentId = agentArg || "claude-code";
+
+  if (!baseUrl) {
+    baseUrl = await ask("OpenViking server URL (e.g. http://127.0.0.1:1933): ");
+  }
+  if (!baseUrl) {
+    console.log("❌ URL is required. Aborting.");
+    process.exit(1);
+  }
+
+  if (!apiKey) {
+    apiKey = await ask("OpenViking API key (press Enter to skip): ");
+  }
+
+  if (!agentArg) {
+    const ans = await ask(`Agent ID [${agentId}]: `);
+    if (ans) agentId = ans;
+  }
+
+  console.log("\n📦 Installing...\n");
+
+  // 1. Copy hooks
+  fs.mkdirSync(HOOKS_DIR, { recursive: true });
+  for (const file of ["auto-recall.cjs", "auto-capture.cjs", "mcp-server.cjs"]) {
+    const src = path.join(PKG_HOOKS_DIR, file);
+    const dst = path.join(HOOKS_DIR, file);
+    fs.copyFileSync(src, dst);
+    console.log(`  ✅ Copied ${file}`);
+  }
+
+  // 2. Patch hooks files with user's config
+  for (const file of ["auto-recall.cjs", "auto-capture.cjs", "mcp-server.cjs"]) {
+    const filePath = path.join(HOOKS_DIR, file);
+    let content = fs.readFileSync(filePath, "utf8");
+    // Replace default values
+    content = content.replace(
+      /const OPENVIKING_BASE_URL = process\.env\.OPENVIKING_BASE_URL \|\| "[^"]*"/,
+      `const OPENVIKING_BASE_URL = process.env.OPENVIKING_BASE_URL || ${JSON.stringify(baseUrl)}`
+    );
+    content = content.replace(
+      /const OPENVIKING_API_KEY = process\.env\.OPENVIKING_API_KEY \|\| "[^"]*"/,
+      `const OPENVIKING_API_KEY = process.env.OPENVIKING_API_KEY || ${JSON.stringify(apiKey || "")}`
+    );
+    content = content.replace(
+      /const OPENVIKING_AGENT_ID = process\.env\.OPENVIKING_AGENT_ID \|\| "[^"]*"/,
+      `const OPENVIKING_AGENT_ID = process.env.OPENVIKING_AGENT_ID || ${JSON.stringify(agentId)}`
+    );
+    fs.writeFileSync(filePath, content, "utf8");
+  }
+  console.log("  ✅ Configured OpenViking connection");
+
+  // 3. Update settings.json (add hooks)
+  const settings = readJson(SETTINGS_PATH) || {};
+  settings.hooks = settings.hooks || {};
+
+  // UserPromptSubmit hook
+  const recallHook = {
+    matcher: "",
+    hooks: [{
+      type: "command",
+      command: `node "${path.join(HOOKS_DIR, "auto-recall.cjs")}"`,
+      timeout: 6000,
+      statusMessage: "Recalling OpenViking memories..."
+    }]
+  };
+
+  // Stop hook
+  const captureHook = {
+    matcher: "",
+    hooks: [{
+      type: "command",
+      command: `node "${path.join(HOOKS_DIR, "auto-capture.cjs")}"`,
+      timeout: 12000,
+      async: true,
+      statusMessage: "Capturing memories to OpenViking..."
+    }]
+  };
+
+  // Add if not already present
+  settings.hooks.UserPromptSubmit = settings.hooks.UserPromptSubmit || [];
+  if (!JSON.stringify(settings.hooks.UserPromptSubmit).includes("openviking")) {
+    settings.hooks.UserPromptSubmit.push(recallHook);
+  }
+
+  settings.hooks.Stop = settings.hooks.Stop || [];
+  if (!JSON.stringify(settings.hooks.Stop).includes("openviking")) {
+    settings.hooks.Stop.push(captureHook);
+  }
+
+  writeJson(SETTINGS_PATH, settings);
+  console.log("  ✅ Added hooks to settings.json");
+
+  // 4. Create .mcp.json in cwd (user can move it)
+  const mcpConfig = {
+    mcpServers: {
+      openviking: {
+        command: "node",
+        args: [path.join(HOOKS_DIR, "mcp-server.cjs")],
+        env: {
+          OPENVIKING_BASE_URL: baseUrl,
+          OPENVIKING_API_KEY: apiKey || "",
+          OPENVIKING_AGENT_ID: agentId,
+        }
+      }
+    }
+  };
+
+  const mcpPath = path.join(process.cwd(), ".mcp.json");
+  if (!fs.existsSync(mcpPath)) {
+    writeJson(mcpPath, mcpConfig);
+    console.log(`  ✅ Created ${mcpPath}`);
+  } else {
+    const existing = readJson(mcpPath) || {};
+    existing.mcpServers = existing.mcpServers || {};
+    if (!existing.mcpServers.openviking) {
+      existing.mcpServers.openviking = mcpConfig.mcpServers.openviking;
+      writeJson(mcpPath, existing);
+      console.log(`  ✅ Added openviking to existing ${mcpPath}`);
+    } else {
+      console.log(`  ⏭️  openviking already in ${mcpPath} — skipped`);
+    }
+  }
+
+  console.log(`
+✅ Setup complete!
+
+Restart Claude Code to activate. You'll see:
+  • "[OpenViking Auto-Recall]" context on every message
+  • Conversations auto-saved to OpenViking
+  • memory_recall / memory_store / memory_forget tools available
+
+To uninstall: npx claude-openviking --uninstall
+`);
+}
+
+// --- Main ---
+
+if (isUninstall) {
+  uninstall();
+} else {
+  install().catch((err) => {
+    console.error("Setup failed:", err.message);
+    process.exit(1);
+  });
+}

package/hooks/auto-capture.cjs

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+/**
+ * OpenViking Auto-Capture Hook for Claude Code
+ *
+ * Runs on Stop: reads the latest conversation turn from the transcript,
+ * sends it to OpenViking for memory extraction.
+ * Mirrors the afterTurn auto-capture behavior of the OpenClaw plugin.
+ */
+
+const fs = require("fs");
+const readline = require("readline");
+
+const OPENVIKING_BASE_URL = process.env.OPENVIKING_BASE_URL || "";
+const OPENVIKING_API_KEY = process.env.OPENVIKING_API_KEY || "";
+const OPENVIKING_AGENT_ID = process.env.OPENVIKING_AGENT_ID || "claude-code";
+const TIMEOUT_MS = 10000;
+const CAPTURE_MAX_LENGTH = 24000;
+const MIN_CAPTURE_LENGTH = 10;
+const MIN_CAPTURE_TURNS = 2;
+const MIN_ASSISTANT_CHARS = 50;
+
+// Skip patterns
+const COMMAND_RE = /^\/[a-z0-9_-]{1,64}\b/i;
+const NON_CONTENT_RE = /^[\p{P}\p{S}\s]+$/u;
+const RELEVANT_MEMORIES_RE = /<relevant-memories>[\s\S]*?<\/relevant-memories>/gi;
+const METADATA_BLOCK_RE = /(?:^|\n)\s*(?:Conversation info|Conversation metadata)\s*(?:\([^)]+\))?\s*:\s*```[\s\S]*?```/gi;
+const QUESTION_ONLY_RE = /^[?？\s]*$/;
+
+// Memory trigger keywords for keyword mode (we use semantic mode by default)
+const CJK_RE = /[\u3040-\u30ff\u3400-\u9fff\uf900-\ufaff\uac00-\ud7af]/;
+
+function sanitize(text) {
+  return text
+    .replace(RELEVANT_MEMORIES_RE, " ")
+    .replace(METADATA_BLOCK_RE, " ")
+    .replace(/\u0000/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function shouldCapture(text) {
+  if (!text || text.length < MIN_CAPTURE_LENGTH) return false;
+  if (text.length > CAPTURE_MAX_LENGTH) return false;
+  if (COMMAND_RE.test(text)) return false;
+  if (NON_CONTENT_RE.test(text)) return false;
+  if (QUESTION_ONLY_RE.test(text)) return false;
+  return true;
+}
+
+async function ovRequest(path, options = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+  try {
+    const res = await fetch(`${OPENVIKING_BASE_URL}${path}`, {
+      ...options,
+      headers: {
+        "Content-Type": "application/json",
+        "X-API-Key": OPENVIKING_API_KEY,
+        "X-OpenViking-Agent": OPENVIKING_AGENT_ID,
+        ...(options.headers || {}),
+      },
+      signal: controller.signal,
+    });
+    const payload = await res.json().catch(() => ({}));
+    return payload.result ?? payload;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Read the last N lines from a JSONL transcript file to extract
+ * the most recent user + assistant messages.
+ */
+async function readRecentMessages(transcriptPath, maxLines = 50) {
+  if (!transcriptPath || !fs.existsSync(transcriptPath)) return [];
+
+  const messages = [];
+  const lines = [];
+
+  // Read last maxLines from file
+  const fileStream = fs.createReadStream(transcriptPath, { encoding: "utf8" });
+  const rl = readline.createInterface({ input: fileStream, crlfDelay: Infinity });
+
+  for await (const line of rl) {
+    lines.push(line);
+    if (lines.length > maxLines * 2) {
+      lines.splice(0, lines.length - maxLines);
+    }
+  }
+
+  // Parse JSONL entries and extract user/assistant messages
+  for (const line of lines.slice(-maxLines)) {
+    if (!line.trim()) continue;
+    try {
+      const entry = JSON.parse(line);
+      // Claude Code transcript format: look for message entries
+      if (entry.type === "human" || entry.type === "user") {
+        const text = extractText(entry);
+        if (text) messages.push({ role: "user", text });
+      } else if (entry.type === "assistant") {
+        const text = extractText(entry);
+        if (text) messages.push({ role: "assistant", text });
+      } else if (entry.role === "user" || entry.role === "human") {
+        const text = extractText(entry);
+        if (text) messages.push({ role: "user", text });
+      } else if (entry.role === "assistant") {
+        const text = extractText(entry);
+        if (text) messages.push({ role: "assistant", text });
+      }
+      // Also handle message wrapper format
+      if (entry.message) {
+        const msg = entry.message;
+        const role = msg.role === "human" ? "user" : msg.role;
+        if (role === "user" || role === "assistant") {
+          const text = extractText(msg);
+          if (text) messages.push({ role, text });
+        }
+      }
+    } catch {
+      // skip unparseable lines
+    }
+  }
+
+  return messages;
+}
+
+function extractText(obj) {
+  if (typeof obj.content === "string") return obj.content.trim();
+  if (typeof obj.text === "string") return obj.text.trim();
+  if (Array.isArray(obj.content)) {
+    const parts = [];
+    for (const block of obj.content) {
+      if (typeof block === "string") parts.push(block);
+      else if (block?.type === "text" && typeof block.text === "string") parts.push(block.text);
+    }
+    return parts.join("\n").trim();
+  }
+  return "";
+}
+
+async function main() {
+  let input = "";
+  for await (const chunk of process.stdin) {
+    input += chunk;
+  }
+
+  let data;
+  try {
+    data = JSON.parse(input);
+  } catch {
+    process.exit(0);
+  }
+
+  const transcriptPath = data.transcript_path;
+  const sessionId = data.session_id || `claude-code-${Date.now()}`;
+
+  // Use session_id as the OV session ID for 1:1 mapping (like OpenClaw plugin)
+  const ovSessionId = `cc-${sessionId}`;
+
+  // Read recent messages from transcript
+  const messages = await readRecentMessages(transcriptPath);
+  if (messages.length === 0) {
+    process.exit(0);
+  }
+
+  // Take the last few messages (current turn)
+  const recentMessages = messages.slice(-6);
+
+  // Quality gate: skip trivial conversations
+  if (recentMessages.length < MIN_CAPTURE_TURNS) {
+    process.exit(0);
+  }
+
+  // Quality gate: skip if assistant responses are too short
+  const assistantText = recentMessages
+    .filter((m) => m.role === "assistant")
+    .map((m) => m.text)
+    .join("");
+  if (assistantText.length < MIN_ASSISTANT_CHARS) {
+    process.exit(0);
+  }
+
+  // Build turn text
+  const turnTexts = recentMessages.map((m) => `[${m.role}]: ${m.text}`);
+  const turnText = turnTexts.join("\n");
+  const sanitized = sanitize(turnText);
+
+  if (!shouldCapture(sanitized)) {
+    process.exit(0);
+  }
+
+  // Truncate if needed
+  const captureText = sanitized.length > CAPTURE_MAX_LENGTH
+    ? sanitized.slice(0, CAPTURE_MAX_LENGTH)
+    : sanitized;
+
+  try {
+    // Send to OpenViking session
+    await ovRequest(`/api/v1/sessions/${encodeURIComponent(ovSessionId)}/messages`, {
+      method: "POST",
+      body: JSON.stringify({ role: "user", content: captureText }),
+    });
+
+    // Commit session to extract memories
+    await ovRequest(`/api/v1/sessions/${encodeURIComponent(ovSessionId)}/commit?wait=false`, {
+      method: "POST",
+      body: JSON.stringify({}),
+    });
+  } catch {
+    // Silently fail - don't block the user
+  }
+
+  process.exit(0);
+}
+
+main().catch(() => process.exit(0));

package/hooks/auto-recall.cjs

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+/**
+ * OpenViking Auto-Recall Hook for Claude Code (v2 — Tiered)
+ *
+ * Runs on UserPromptSubmit: searches user + agent memory spaces,
+ * merges results, injects top-3 as L1 overview + remainder as L0 abstract.
+ */
+
+const OPENVIKING_BASE_URL = process.env.OPENVIKING_BASE_URL || "";
+const OPENVIKING_API_KEY = process.env.OPENVIKING_API_KEY || "";
+const OPENVIKING_AGENT_ID = process.env.OPENVIKING_AGENT_ID || "claude-code";
+
+// Recall parameters
+const RECALL_TOKEN_BUDGET = 2000;
+const RECALL_SCORE_THRESHOLD = 0.15;
+const SEARCH_LIMIT_PER_SPACE = 20;
+const L1_SLOTS = 3;
+const L1_MAX_CHARS = 1200;
+const L0_MAX_CHARS = 200;
+const TIMEOUT_MS = 5000;
+const MIN_QUERY_LENGTH = 5;
+
+// Skip patterns
+const COMMAND_RE = /^\/[a-z0-9_-]{1,64}\b/i;
+const NON_CONTENT_RE = /^[\p{P}\p{S}\s]+$/u;
+
+function clampScore(v) {
+  if (typeof v !== "number" || Number.isNaN(v)) return 0;
+  return Math.max(0, Math.min(1, v));
+}
+
+function estimateTokens(text) {
+  return Math.ceil((text || "").length / 4);
+}
+
+async function ovFind(query, targetUri) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+  try {
+    const res = await fetch(`${OPENVIKING_BASE_URL}/api/v1/search/find`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-API-Key": OPENVIKING_API_KEY,
+        "X-OpenViking-Agent": OPENVIKING_AGENT_ID,
+      },
+      body: JSON.stringify({
+        query,
+        ...(targetUri ? { target_uri: targetUri } : {}),
+        limit: SEARCH_LIMIT_PER_SPACE,
+        score_threshold: 0,
+      }),
+      signal: controller.signal,
+    });
+    const payload = await res.json().catch(() => ({}));
+    if (!res.ok) return [];
+    return payload.result?.memories || payload.memories || [];
+  } catch {
+    return [];
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function main() {
+  // Read stdin
+  let input = "";
+  for await (const chunk of process.stdin) {
+    input += chunk;
+  }
+
+  let prompt;
+  try {
+    const data = JSON.parse(input);
+    prompt = data.prompt || "";
+  } catch {
+    process.exit(0);
+  }
+
+  // Clean up the prompt text
+  const queryText = prompt
+    .replace(/<relevant-memories>[\s\S]*?<\/relevant-memories>/gi, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+
+  // Skip if too short, is a command, or is pure punctuation
+  if (
+    queryText.length < MIN_QUERY_LENGTH ||
+    COMMAND_RE.test(queryText) ||
+    NON_CONTENT_RE.test(queryText)
+  ) {
+    process.exit(0);
+  }
+
+  // Split-space search: user memories + agent memories + global fallback
+  const [userMems, agentMems, globalMems] = await Promise.all([
+    ovFind(queryText, "viking://user/memories"),
+    ovFind(queryText, "viking://agent/memories"),
+    ovFind(queryText, null),
+  ]);
+
+  // Merge and deduplicate by URI (split-space results first, then global)
+  const uriSet = new Set();
+  const allMems = [];
+  for (const item of [...userMems, ...agentMems, ...globalMems]) {
+    if (uriSet.has(item.uri)) continue;
+    uriSet.add(item.uri);
+    allMems.push(item);
+  }
+
+  // Filter by score threshold and sort descending
+  const scored = allMems
+    .filter((m) => clampScore(m.score) >= RECALL_SCORE_THRESHOLD)
+    .sort((a, b) => clampScore(b.score) - clampScore(a.score));
+
+  // Deduplicate by abstract content
+  const seen = new Set();
+  const candidates = [];
+  for (const item of scored) {
+    const key = (item.abstract || item.overview || "").trim().toLowerCase() || item.uri;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    candidates.push(item);
+  }
+
+  if (candidates.length === 0) {
+    process.exit(0);
+  }
+
+  // Build tiered injection lines within token budget
+  let budgetRemaining = RECALL_TOKEN_BUDGET;
+  const lines = [];
+
+  for (let i = 0; i < candidates.length; i++) {
+    if (budgetRemaining <= 0) break;
+    const item = candidates[i];
+
+    let content;
+    if (i < L1_SLOTS) {
+      // Top-N: use L1 overview for richer context
+      content = (item.overview || item.abstract || item.uri).trim();
+      if (content.length > L1_MAX_CHARS) {
+        content = content.slice(0, L1_MAX_CHARS) + "...";
+      }
+    } else {
+      // Remainder: use L0 abstract for broad coverage
+      content = (item.abstract || item.uri).trim();
+      if (content.length > L0_MAX_CHARS) {
+        content = content.slice(0, L0_MAX_CHARS) + "...";
+      }
+    }
+
+    const line = `- [${item.category || "memory"}] ${content}`;
+    const lineTokens = estimateTokens(line);
+
+    // First line always included even if over budget
+    if (lineTokens > budgetRemaining && lines.length > 0) break;
+
+    lines.push(line);
+    budgetRemaining -= lineTokens;
+  }
+
+  if (lines.length === 0) {
+    process.exit(0);
+  }
+
+  const memoryContext =
+    "[OpenViking Auto-Recall] The following long-term memories may be relevant to this conversation:\n" +
+    lines.join("\n");
+
+  const output = {
+    hookSpecificOutput: {
+      hookEventName: "UserPromptSubmit",
+      additionalContext: memoryContext,
+    },
+  };
+
+  process.stdout.write(JSON.stringify(output));
+  process.exit(0);
+}
+
+main().catch(() => process.exit(0));

package/hooks/mcp-server.cjs

@@ -0,0 +1,314 @@
+#!/usr/bin/env node
+/**
+ * OpenViking MCP Server for Claude Code
+ *
+ * Provides memory_recall, memory_store, memory_forget tools
+ * that connect to the same OpenViking backend used by the OpenClaw plugin.
+ *
+ * Protocol: MCP stdio (JSON-RPC 2.0 over stdin/stdout)
+ */
+
+const OPENVIKING_BASE_URL = process.env.OPENVIKING_BASE_URL || "";
+const OPENVIKING_API_KEY = process.env.OPENVIKING_API_KEY || "";
+const OPENVIKING_AGENT_ID = process.env.OPENVIKING_AGENT_ID || "claude-code";
+const OPENVIKING_TIMEOUT_MS = 15000;
+const RECALL_LIMIT = 6;
+const RECALL_SCORE_THRESHOLD = 0.15;
+const RECALL_MAX_CONTENT_CHARS = 500;
+
+// --- HTTP client ---
+
+async function ovRequest(path, options = {}, agentId) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), OPENVIKING_TIMEOUT_MS);
+  try {
+    const headers = {
+      "Content-Type": "application/json",
+      "X-API-Key": OPENVIKING_API_KEY,
+      "X-OpenViking-Agent": agentId || OPENVIKING_AGENT_ID,
+    };
+    const res = await fetch(`${OPENVIKING_BASE_URL}${path}`, {
+      ...options,
+      headers: { ...headers, ...(options.headers || {}) },
+      signal: controller.signal,
+    });
+    const payload = await res.json().catch(() => ({}));
+    if (!res.ok || payload.status === "error") {
+      const code = payload.error?.code ? ` [${payload.error.code}]` : "";
+      const message = payload.error?.message || `HTTP ${res.status}`;
+      throw new Error(`OpenViking${code}: ${message}`);
+    }
+    return payload.result ?? payload;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// --- Memory helpers ---
+
+function clampScore(v) {
+  if (typeof v !== "number" || Number.isNaN(v)) return 0;
+  return Math.max(0, Math.min(1, v));
+}
+
+function dedupeMemories(items, limit, scoreThreshold) {
+  const seen = new Set();
+  const result = [];
+  const sorted = [...items].sort((a, b) => clampScore(b.score) - clampScore(a.score));
+  for (const item of sorted) {
+    if (clampScore(item.score) < scoreThreshold) continue;
+    if (item.level !== 2) continue;
+    const key = (item.abstract || item.overview || "").trim().toLowerCase() || item.uri;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push(item);
+    if (result.length >= limit) break;
+  }
+  return result;
+}
+
+const MEMORY_URI_RE = /^viking:\/\/(user|agent)\/(?:[^/]+\/)?memories(?:\/|$)/;
+function isMemoryUri(uri) {
+  return MEMORY_URI_RE.test(uri);
+}
+
+// --- Tool implementations ---
+
+async function memoryRecall(params) {
+  const { query } = params;
+  const limit = params.limit || RECALL_LIMIT;
+  const scoreThreshold = params.scoreThreshold ?? RECALL_SCORE_THRESHOLD;
+  const targetUri = params.targetUri;
+  const requestLimit = Math.max(limit * 4, 20);
+
+  let allMemories;
+  if (targetUri) {
+    const result = await ovRequest("/api/v1/search/find", {
+      method: "POST",
+      body: JSON.stringify({ query, target_uri: targetUri, limit: requestLimit, score_threshold: 0 }),
+    });
+    allMemories = result.memories || [];
+  } else {
+    // Search ALL spaces (no target_uri) to avoid space-resolution mismatch
+    const result = await ovRequest("/api/v1/search/find", {
+      method: "POST",
+      body: JSON.stringify({ query, limit: requestLimit, score_threshold: 0 }),
+    });
+    allMemories = result.memories || [];
+  }
+
+  const memories = dedupeMemories(allMemories, limit, scoreThreshold);
+  if (memories.length === 0) {
+    return { content: [{ type: "text", text: "No relevant OpenViking memories found." }] };
+  }
+
+  // Fetch full content for each memory
+  const lines = [];
+  for (const item of memories) {
+    let content = item.abstract?.trim() || item.uri;
+    if (item.level === 2) {
+      try {
+        const full = await ovRequest(`/api/v1/content/read?uri=${encodeURIComponent(item.uri)}`);
+        if (typeof full === "string" && full.trim()) {
+          content = full.trim();
+        }
+      } catch {}
+    }
+    if (content.length > RECALL_MAX_CONTENT_CHARS) {
+      content = content.slice(0, RECALL_MAX_CONTENT_CHARS) + "...";
+    }
+    const score = (clampScore(item.score) * 100).toFixed(0);
+    lines.push(`- [${item.category || "memory"}] ${content} (${score}%)`);
+  }
+
+  return {
+    content: [{ type: "text", text: `Found ${memories.length} memories:\n\n${lines.join("\n")}` }],
+  };
+}
+
+async function memoryStore(params) {
+  const { text, sessionId } = params;
+  const role = params.role || "user";
+  const sid = sessionId || `claude-code-${Date.now()}`;
+
+  await ovRequest(`/api/v1/sessions/${encodeURIComponent(sid)}/messages`, {
+    method: "POST",
+    body: JSON.stringify({ role, content: text }),
+  });
+  const commitResult = await ovRequest(`/api/v1/sessions/${encodeURIComponent(sid)}/commit?wait=true`, {
+    method: "POST",
+    body: JSON.stringify({}),
+  });
+  const count = commitResult.memories_extracted || 0;
+  return {
+    content: [{ type: "text", text: `Stored in OpenViking session ${sid}, extracted ${count} memories.` }],
+  };
+}
+
+async function memoryForget(params) {
+  const { uri, query } = params;
+
+  if (uri) {
+    if (!isMemoryUri(uri)) {
+      return { content: [{ type: "text", text: `Refusing to delete non-memory URI: ${uri}` }] };
+    }
+    await ovRequest(`/api/v1/fs?uri=${encodeURIComponent(uri)}&recursive=false`, { method: "DELETE" });
+    return { content: [{ type: "text", text: `Forgotten: ${uri}` }] };
+  }
+
+  if (!query) {
+    return { content: [{ type: "text", text: "Provide uri or query." }] };
+  }
+
+  const result = await ovRequest("/api/v1/search/find", {
+    method: "POST",
+    body: JSON.stringify({ query, limit: 20, score_threshold: 0 }),
+  });
+  const candidates = dedupeMemories(result.memories || [], 20, RECALL_SCORE_THRESHOLD)
+    .filter((m) => isMemoryUri(m.uri));
+
+  if (candidates.length === 0) {
+    return { content: [{ type: "text", text: "No matching memories found." }] };
+  }
+
+  const top = candidates[0];
+  if (candidates.length === 1 && clampScore(top.score) >= 0.85) {
+    await ovRequest(`/api/v1/fs?uri=${encodeURIComponent(top.uri)}&recursive=false`, { method: "DELETE" });
+    return { content: [{ type: "text", text: `Forgotten: ${top.uri}` }] };
+  }
+
+  const list = candidates
+    .map((item) => `- ${item.uri} (${(clampScore(item.score) * 100).toFixed(0)}%)`)
+    .join("\n");
+  return {
+    content: [{ type: "text", text: `Found ${candidates.length} candidates. Specify uri:\n${list}` }],
+  };
+}
+
+// --- MCP Protocol ---
+
+const TOOLS = [
+  {
+    name: "memory_recall",
+    description: "Search long-term memories from OpenViking. Use when you need past user preferences, facts, decisions, or context from previous conversations.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Search query" },
+        limit: { type: "number", description: "Max results (default: 6)" },
+        scoreThreshold: { type: "number", description: "Minimum score 0-1 (default: 0.15)" },
+        targetUri: { type: "string", description: "Search scope URI (e.g. viking://user/memories)" },
+      },
+      required: ["query"],
+    },
+  },
+  {
+    name: "memory_store",
+    description: "Store information in OpenViking long-term memory. Use to save important facts, preferences, decisions, or context for future recall.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        text: { type: "string", description: "Information to store" },
+        role: { type: "string", description: "Session role (default: user)" },
+        sessionId: { type: "string", description: "Session ID (auto-generated if omitted)" },
+      },
+      required: ["text"],
+    },
+  },
+  {
+    name: "memory_forget",
+    description: "Delete a memory by URI, or search then delete when a strong match is found.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        uri: { type: "string", description: "Exact memory URI to delete" },
+        query: { type: "string", description: "Search query to find memory" },
+      },
+    },
+  },
+];
+
+const TOOL_HANDLERS = {
+  memory_recall: memoryRecall,
+  memory_store: memoryStore,
+  memory_forget: memoryForget,
+};
+
+function makeResponse(id, result) {
+  return JSON.stringify({ jsonrpc: "2.0", id, result });
+}
+
+function makeError(id, code, message) {
+  return JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } });
+}
+
+async function handleMessage(msg) {
+  const { id, method, params } = msg;
+
+  switch (method) {
+    case "initialize":
+      return makeResponse(id, {
+        protocolVersion: "2024-11-05",
+        capabilities: { tools: {} },
+        serverInfo: { name: "openviking", version: "1.0.0" },
+      });
+
+    case "notifications/initialized":
+      return null; // no response needed
+
+    case "tools/list":
+      return makeResponse(id, { tools: TOOLS });
+
+    case "tools/call": {
+      const toolName = params?.name;
+      const handler = TOOL_HANDLERS[toolName];
+      if (!handler) {
+        return makeError(id, -32601, `Unknown tool: ${toolName}`);
+      }
+      try {
+        const result = await handler(params.arguments || {});
+        return makeResponse(id, result);
+      } catch (err) {
+        return makeResponse(id, {
+          content: [{ type: "text", text: `Error: ${err.message}` }],
+          isError: true,
+        });
+      }
+    }
+
+    case "ping":
+      return makeResponse(id, {});
+
+    default:
+      if (id != null) {
+        return makeError(id, -32601, `Method not found: ${method}`);
+      }
+      return null;
+  }
+}
+
+// --- stdio transport ---
+
+let buffer = "";
+
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", async (chunk) => {
+  buffer += chunk;
+  let newlineIdx;
+  while ((newlineIdx = buffer.indexOf("\n")) !== -1) {
+    const line = buffer.slice(0, newlineIdx).trim();
+    buffer = buffer.slice(newlineIdx + 1);
+    if (!line) continue;
+    try {
+      const msg = JSON.parse(line);
+      const response = await handleMessage(msg);
+      if (response) {
+        process.stdout.write(response + "\n");
+      }
+    } catch (err) {
+      process.stderr.write(`MCP parse error: ${err.message}\n`);
+    }
+  }
+});
+
+process.stdin.on("end", () => process.exit(0));

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "claude-code-openviking",
+  "version": "0.2.0",
+  "description": "OpenViking long-term memory integration for Claude Code — auto-recall, auto-capture, and MCP tools",
+  "author": {
+    "name": "Bill Zhao",
+    "email": "zhaodibill@gmail.com",
+    "url": "https://www.linkedin.com/in/billzhaodi/"
+  },
+  "license": "MIT",
+  "bin": {
+    "openviking-claude-code": "bin/setup.cjs"
+  },
+  "files": [
+    "hooks/*.cjs",
+    "bin/*.cjs",
+    "README.md"
+  ],
+  "keywords": ["claude-code", "openviking", "memory", "mcp", "auto-recall", "long-term-memory"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/billzhao9/claude-openviking"
+  }
+}