@openviking/openclaw-plugin 2026.5.21 → 2026.6.2

package/README.md

@@ -23,8 +23,9 @@ The agent runs install → setup → restart → verify automatically. See [INST
 
 | Stage | What happens |
 |-------|-------------|
-| **Every turn** (`afterTurn`) | Your messages are archived into an OpenViking session |
-| **On `/compact`** (`compact`) | Archived messages are extracted into long-term memories |
+| **Every turn** (`afterTurn`) | New messages are appended to an OpenViking session; commit/extraction is threshold-triggered |
+| **Explicit remember** (`memory_store`) | Important long-term facts can be written and committed immediately |
+| **On `/compact`** (`compact`) | Pending session messages are committed and extracted into long-term memories |
 | **Before each reply** (`assemble`) | Relevant memories are auto-retrieved and injected into context |
 
 ## Tools
@@ -34,13 +35,16 @@ Once installed, the plugin provides these agent tools:
 | Tool | Purpose |
 |------|---------|
 | `memory_recall` | Explicit long-term memory search |
-| `memory_store` | Persist important information immediately |
+| `memory_store` | Persist explicit long-term facts immediately |
 | `memory_forget` | Delete memories by URI or query |
 | `ov_archive_search` | Search across archives by keyword |
 | `ov_archive_expand` | Expand an archive back to raw messages |
 | `add_resource` | Import documents, URLs, or Git repos |
 | `add_skill` | Import agent skills |
-| `memory_search` | Search imported resources and skills |
+| `ov_search` | Search imported resources and skills |
+| `openviking_tool_result_read` | Restore the full original content of an externalized tool result |
+| `openviking_tool_result_search` | Search inside an externalized tool result by keyword |
+| `openviking_tool_result_list` | List externalized tool results in the current session |
 
 ## Data Flow & Privacy
 
@@ -203,6 +207,18 @@ After that, the plugin checks `pending_tokens`. Once the session crosses `commit
 - the current turn is not blocked waiting for extraction
 - if `logFindRequests` is enabled, the logs include the task id and follow-up extraction detail
 
+This automatic path is best-effort and commit-dependent. Short but important facts can stay only in the live session until a threshold commit, `/compact`, or an explicit store happens.
+
+### Explicit long-term memory writes
+
+When the user explicitly asks the agent to remember, save, or store an important long-term fact, preference, project, or decision, prefer `memory_store` over waiting for normal auto-capture. `memory_store` writes the text to an OpenViking session and calls `commit(wait=true)`, so it is the reliable integration-side path for facts that should be available as long-term memory as soon as possible.
+
+Use it as a complement to auto-capture, not a replacement:
+
+- auto-capture still preserves ordinary conversation flow and batches extraction for cost and latency
+- `memory_store` is for explicit durable-memory intent such as "remember my main project is X" or "save this preference"
+- if `memory_store` commits but extracts 0 memories, check the OpenViking server extraction/model configuration; the explicit path triggered extraction, but the extractor did not produce a memory
+
 ### What `compact()` does
 
 `compact()` is the stricter synchronous boundary:
@@ -219,22 +235,22 @@ So `afterTurn()` is closer to "incremental append plus threshold-triggered async
 Beyond automatic behavior, the plugin exposes seven tools directly:
 
 - `memory_recall`: explicit long-term memory search
-- `memory_store`: write text into an OpenViking session and trigger commit
+- `memory_store`: write explicit long-term facts into an OpenViking session and trigger commit
 - `memory_forget`: delete by URI, or search first and remove a single strong match
 - `ov_archive_expand`: expand a concrete archive back into raw messages
 - `add_resource`: import a document, directory, URL, or Git repository as an OpenViking resource
 - `add_skill`: import or register an OpenViking agent skill
-- `memory_search`: search OpenViking resources and skills, especially after importing them
+- `ov_search`: search OpenViking resources and skills, especially after importing them
 
 They serve different roles:
 
 - automatic recall covers the default case where the model does not know what to search yet
 - `memory_recall` gives the model an explicit follow-up search path
-- `memory_store` is for immediately persisting clearly important information
+- `memory_store` is for immediately persisting clearly important information when the user expresses durable-memory intent
 - `ov_archive_expand` is the "go back to archive detail" escape hatch when summaries are not enough
 - `add_resource` lets the agent save explicit document or repository import requests without asking the user to remember slash commands
 - `add_skill` imports skills into OpenViking, while `add_resource` imports resources
-- `memory_search` closes the loop after import by letting the user or agent confirm and consume resources and skills
+- `ov_search` closes the loop after import by letting the user or agent confirm and consume resources and skills
 
 `ov_archive_expand` is especially important because `assemble()` normally returns archive summaries and indexes, not the full raw transcript.
 
@@ -250,8 +266,8 @@ The plugin also registers explicit slash commands for manual imports:
 ```text
 /add-resource ./README.md --to viking://resources/openviking-readme --wait
 /add-skill ./skills/install-openviking-memory --wait
-/memory-search "OpenViking install" --uri viking://resources/openviking-readme
-/memory-search "memory install skill" --uri viking://agent/skills
+/ov-search "OpenViking install" --uri viking://resources/openviking-readme
+/ov-search "memory install skill" --uri viking://agent/skills
 ```
 
 Resource import supports remote URLs, Git URLs, local files, local directories, and uploaded zip files. OpenViking's built-in parsers cover common documents and media such as Markdown, text, PDF, HTML, Word, PowerPoint, Excel, EPUB, images, audio, and video. Directory imports also accept common code, documentation, and config file extensions such as `.py`, `.js`, `.ts`, `.go`, `.rs`, `.java`, `.cpp`, `.json`, `.yaml`, `.toml`, `.csv`, `.rst`, `.proto`, `.tf`, and `.vue`.

package/auto-recall.ts

@@ -8,6 +8,7 @@ import {
 } from "./memory-ranking.js";
 import { quickRecallPrecheck, withTimeout } from "./process-manager.js";
 import { sanitizeUserTextForCapture } from "./text-utils.js";
+import { estimateTextTokens } from "./token-estimator.js";
 
 const AUTO_RECALL_TIMEOUT_MS = 5_000;
 const RECALL_QUERY_MAX_CHARS = 4_000;
@@ -51,16 +52,44 @@ export function prepareRecallQuery(rawText: string): PreparedRecallQuery {
   };
 }
 
-/** Estimate token count using chars/4 heuristic for diagnostics. */
+/** Estimate token count using the shared CJK-aware fallback for diagnostics. */
 export function estimateTokenCount(text: string): number {
-  if (!text) return 0;
-  return Math.ceil(text.length / 4);
+  return estimateTextTokens(text);
 }
 
 export type BuildMemoryLinesOptions = {
   recallPreferAbstract: boolean;
+  includeUri?: boolean;
 };
 
+function memoryCategory(item: FindResultItem): string {
+  return item.category?.trim() || "memory";
+}
+
+function indentContent(content: string): string {
+  return content
+    .split("\n")
+    .map((line) => `  ${line}`)
+    .join("\n");
+}
+
+function formatMemoryLine(
+  item: FindResultItem,
+  content: string,
+  options: BuildMemoryLinesOptions,
+): string {
+  const category = memoryCategory(item);
+  if (!options.includeUri) {
+    return `- [${category}] ${content}`;
+  }
+
+  return [
+    `- [${category}]`,
+    `  <uri>${item.uri}</uri>`,
+    indentContent(content),
+  ].join("\n");
+}
+
 async function resolveMemoryContent(
   item: FindResultItem,
   readFn: (uri: string) => Promise<string>,
@@ -95,7 +124,7 @@ export async function buildMemoryLines(
   const lines: string[] = [];
   for (const item of memories) {
     const content = await resolveMemoryContent(item, readFn, options);
-    lines.push(`- [${item.category ?? "memory"}] ${content}`);
+    lines.push(formatMemoryLine(item, content, options));
   }
   return lines;
 }
@@ -128,7 +157,7 @@ export async function buildMemoryLinesWithBudget(
     }
 
     const content = await resolveMemoryContent(item, readFn, options);
-    const line = `- [${item.category ?? "memory"}] ${content}`;
+    const line = formatMemoryLine(item, content, options);
     const separatorChars = lines.length > 0 ? 1 : 0;
     const projectedChars = totalChars + separatorChars + line.length;
 
@@ -170,7 +199,7 @@ export async function buildAutoRecallContext(params: {
     return { memoryCount: 0, estimatedTokens: 0 };
   }
 
-  const precheck = await quickRecallPrecheck(cfg.baseUrl);
+  const precheck = await quickRecallPrecheck(client, agentId);
   if (!precheck.ok) {
     verbose?.(`openviking: skipping auto-recall because precheck failed (${precheck.reason})`);
     return { memoryCount: 0, estimatedTokens: 0 };
@@ -231,6 +260,7 @@ export async function buildAutoRecallContext(params: {
         {
           recallPreferAbstract: cfg.recallPreferAbstract,
           recallMaxInjectedChars: cfg.recallMaxInjectedChars,
+          includeUri: true,
         },
       );
 

package/client.ts

@@ -362,8 +362,8 @@ export class OpenVikingClient {
     }
   }
 
-  async healthCheck(): Promise<void> {
-    await this.request<{ status: string }>("/health");
+  async healthCheck(agentId?: string, requestTimeoutMs?: number): Promise<void> {
+    await this.request<{ status: string }>("/health", {}, agentId, requestTimeoutMs);
   }
 
   private async getRuntimeIdentity(agentId?: string): Promise<RuntimeIdentity> {

package/context-engine.ts

@@ -18,6 +18,11 @@ import {
   toJsonLog,
 } from "./memory-ranking.js";
 import { sanitizeToolUseResultPairing } from "./session-transcript-repair.js";
+import {
+  estimateAgentMessageTokens,
+  estimateAgentMessagesTokens,
+  estimateTextTokens,
+} from "./token-estimator.js";
 
 type AgentMessage = {
   role?: string;
@@ -156,14 +161,11 @@ function allocateContextBudget(totalBudget: number, instructionTokens = 0): Cont
 }
 
 function roughEstimate(messages: AgentMessage[]): number {
-  return Math.ceil(JSON.stringify(messages).length / 4);
+  return estimateAgentMessagesTokens(messages);
 }
 
 function msgTokenEstimate(msg: AgentMessage): number {
-  const raw = (msg as Record<string, unknown>).content;
-  if (typeof raw === "string") return Math.ceil(raw.length / 4);
-  if (Array.isArray(raw)) return Math.ceil(JSON.stringify(raw).length / 4);
-  return 1;
+  return estimateAgentMessageTokens(msg);
 }
 
 function normalizeTimestamp(value: unknown): string | undefined {
@@ -671,7 +673,7 @@ function buildSystemPromptAddition(): string {
 
 function buildInstructionPrompt(): { text: string; tokens: number } {
   const text = buildSystemPromptAddition();
-  return { text, tokens: Math.ceil(text.length / 4) };
+  return { text, tokens: estimateTextTokens(text) };
 }
 
 function buildArchiveMemory(

package/dist/auto-recall.js

@@ -1,6 +1,7 @@
 import { pickMemoriesForInjection, postProcessMemories, summarizeInjectionMemories, toJsonLog, } from "./memory-ranking.js";
 import { quickRecallPrecheck, withTimeout } from "./process-manager.js";
 import { sanitizeUserTextForCapture } from "./text-utils.js";
+import { estimateTextTokens } from "./token-estimator.js";
 const AUTO_RECALL_TIMEOUT_MS = 5_000;
 const RECALL_QUERY_MAX_CHARS = 4_000;
 export const AUTO_RECALL_SOURCE_MARKER = "Source: openviking-auto-recall";
@@ -25,11 +26,29 @@ export function prepareRecallQuery(rawText) {
         finalChars: query.length,
     };
 }
-/** Estimate token count using chars/4 heuristic for diagnostics. */
+/** Estimate token count using the shared CJK-aware fallback for diagnostics. */
 export function estimateTokenCount(text) {
-    if (!text)
-        return 0;
-    return Math.ceil(text.length / 4);
+    return estimateTextTokens(text);
+}
+function memoryCategory(item) {
+    return item.category?.trim() || "memory";
+}
+function indentContent(content) {
+    return content
+        .split("\n")
+        .map((line) => `  ${line}`)
+        .join("\n");
+}
+function formatMemoryLine(item, content, options) {
+    const category = memoryCategory(item);
+    if (!options.includeUri) {
+        return `- [${category}] ${content}`;
+    }
+    return [
+        `- [${category}]`,
+        `  <uri>${item.uri}</uri>`,
+        indentContent(content),
+    ].join("\n");
 }
 async function resolveMemoryContent(item, readFn, options) {
     let content;
@@ -57,7 +76,7 @@ export async function buildMemoryLines(memories, readFn, options) {
     const lines = [];
     for (const item of memories) {
         const content = await resolveMemoryContent(item, readFn, options);
-        lines.push(`- [${item.category ?? "memory"}] ${content}`);
+        lines.push(formatMemoryLine(item, content, options));
     }
     return lines;
 }
@@ -78,7 +97,7 @@ export async function buildMemoryLinesWithBudget(memories, readFn, options) {
             break;
         }
         const content = await resolveMemoryContent(item, readFn, options);
-        const line = `- [${item.category ?? "memory"}] ${content}`;
+        const line = formatMemoryLine(item, content, options);
         const separatorChars = lines.length > 0 ? 1 : 0;
         const projectedChars = totalChars + separatorChars + line.length;
         if (projectedChars > charBudget) {
@@ -105,7 +124,7 @@ export async function buildAutoRecallContext(params) {
     if (!cfg.autoRecall || queryText.length < 5) {
         return { memoryCount: 0, estimatedTokens: 0 };
     }
-    const precheck = await quickRecallPrecheck(cfg.baseUrl);
+    const precheck = await quickRecallPrecheck(client, agentId);
     if (!precheck.ok) {
         verbose?.(`openviking: skipping auto-recall because precheck failed (${precheck.reason})`);
         return { memoryCount: 0, estimatedTokens: 0 };
@@ -154,6 +173,7 @@ export async function buildAutoRecallContext(params) {
         const { lines: memoryLines, estimatedTokens } = await buildMemoryLinesWithBudget(memories, (uri) => client.read(uri, agentId), {
             recallPreferAbstract: cfg.recallPreferAbstract,
             recallMaxInjectedChars: cfg.recallMaxInjectedChars,
+            includeUri: true,
         });
         if (memoryLines.length === 0) {
             verbose?.(`openviking: skipping auto-recall injection; no complete memories fit maxInjectedChars=${cfg.recallMaxInjectedChars}`);

package/dist/client.js

@@ -155,8 +155,8 @@ export class OpenVikingClient {
             clearTimeout(timer);
         }
     }
-    async healthCheck() {
-        await this.request("/health");
+    async healthCheck(agentId, requestTimeoutMs) {
+        await this.request("/health", {}, agentId, requestTimeoutMs);
     }
     async getRuntimeIdentity(agentId) {
         const effectiveAgentId = this.resolveEffectiveAgentId(agentId);

package/dist/context-engine.js

@@ -4,6 +4,7 @@ import { AUTO_RECALL_SOURCE_MARKER, buildAutoRecallContext, prepareRecallQuery,
 import { compileSessionPatterns, extractNewTurnMessages, shouldBypassSession, } from "./text-utils.js";
 import { toJsonLog, } from "./memory-ranking.js";
 import { sanitizeToolUseResultPairing } from "./session-transcript-repair.js";
+import { estimateAgentMessageTokens, estimateAgentMessagesTokens, estimateTextTokens, } from "./token-estimator.js";
 export function toRoleId(senderId) {
     if (!senderId) {
         return undefined;
@@ -30,15 +31,10 @@ function allocateContextBudget(totalBudget, instructionTokens = 0) {
     return { archiveMemory, sessionContext, reserved };
 }
 function roughEstimate(messages) {
-    return Math.ceil(JSON.stringify(messages).length / 4);
+    return estimateAgentMessagesTokens(messages);
 }
 function msgTokenEstimate(msg) {
-    const raw = msg.content;
-    if (typeof raw === "string")
-        return Math.ceil(raw.length / 4);
-    if (Array.isArray(raw))
-        return Math.ceil(JSON.stringify(raw).length / 4);
-    return 1;
+    return estimateAgentMessageTokens(msg);
 }
 function normalizeTimestamp(value) {
     if (typeof value === "number" && Number.isFinite(value)) {
@@ -503,7 +499,7 @@ function buildSystemPromptAddition() {
 }
 function buildInstructionPrompt() {
     const text = buildSystemPromptAddition();
-    return { text, tokens: Math.ceil(text.length / 4) };
+    return { text, tokens: estimateTextTokens(text) };
 }
 function buildArchiveMemory(archiveOverview, _preAbstracts, _budget) {
     const messages = [];

package/dist/index.js

@@ -8,6 +8,7 @@ import { clampScore, postProcessMemories, pickMemoriesForInjection, } from "./me
 import { createMemoryOpenVikingContextEngine, openClawSessionToOvStorageId, openClawSessionRefToOvStorageId, } from "./context-engine.js";
 import { buildMemoryLines, buildMemoryLinesWithBudget, estimateTokenCount, prepareRecallQuery, } from "./auto-recall.js";
 export { buildMemoryLines, buildMemoryLinesWithBudget, estimateTokenCount, prepareRecallQuery, };
+export { estimateAgentMessageTokens, estimateAgentMessagesTokens, estimateSerializedTokens, estimateTextTokens, } from "./token-estimator.js";
 function parseToolResultRef(value) {
     const raw = typeof value === "string" ? value.trim() : "";
     if (!raw) {
@@ -205,13 +206,13 @@ export function parseAddSkillCommandArgs(args) {
         timeout: getNumberFlag(parsed.flags, "timeout"),
     };
 }
-export function parseMemorySearchCommandArgs(args) {
+export function parseOVSearchCommandArgs(args) {
     const parsed = parseFlagArgs(args);
-    // `/memory-search` only accepts a single query string, so positional segments are
+    // `/ov-search` only accepts a single query string, so positional segments are
     // always re-joined to preserve unquoted multi-word searches.
     const query = parsed.positionals.join(" ").trim();
     if (!query) {
-        throw new Error('Usage: /memory-search "<query>" [--uri URI] [--limit N]');
+        throw new Error('Usage: /ov-search "<query>" [--uri URI] [--limit N]');
     }
     return {
         query,
@@ -482,7 +483,7 @@ const contextEnginePlugin = {
                 total: memories.length + resources.length + skills.length,
             };
         };
-        const formatMemorySearchRows = (result) => {
+        const formatOVSearchRows = (result) => {
             const truncateSummary = (value, maxChars = 220) => {
                 const collapsed = value.replace(/\s+/g, " ").trim();
                 if (collapsed.length <= maxChars) {
@@ -519,7 +520,7 @@ const contextEnginePlugin = {
                 }),
             ];
         };
-        const formatMemorySearchText = (query, uri, result) => {
+        const formatOVSearchText = (query, uri, result) => {
             if ((result.total ?? 0) <= 0) {
                 const scope = uri ? ` under ${uri}` : "";
                 return `No OpenViking resource or skill results found for "${query}"${scope}.`;
@@ -528,11 +529,11 @@ const contextEnginePlugin = {
             const lines = [
                 `Found ${result.total ?? 0} OpenViking results for "${query}"${scope}`,
                 "",
-                ...formatMemorySearchRows(result),
+                ...formatOVSearchRows(result),
             ].filter((line, index, all) => line || (all[index - 1] && all[index + 1]));
             return lines.join("\n");
         };
-        const memorySearchOpenViking = async (input, agentId) => {
+        const searchOpenViking = async (input, agentId) => {
             const query = input.query.trim();
             if (!query) {
                 throw new Error("query is required");
@@ -572,7 +573,7 @@ const contextEnginePlugin = {
                 result = mergeFindResults(successful);
             }
             return {
-                content: [{ type: "text", text: formatMemorySearchText(query, input.uri, result) }],
+                content: [{ type: "text", text: formatOVSearchText(query, input.uri, result) }],
                 details: {
                     action: "searched",
                     query,
@@ -639,8 +640,8 @@ const contextEnginePlugin = {
             },
         }), { name: "add_skill" });
         api.registerTool((ctx) => ({
-            name: "memory_search",
-            label: "Memory Search (OpenViking)",
+            name: "ov_search",
+            label: "Search (OpenViking)",
             description: "Search OpenViking resources and skills. Use after importing, or when the user asks to search OpenViking resources or skills.",
             parameters: Type.Object({
                 query: Type.String({ description: "Search query" }),
@@ -649,16 +650,16 @@ const contextEnginePlugin = {
             }),
             async execute(_toolCallId, params) {
                 if (isBypassedSession(ctx)) {
-                    return makeBypassedToolResult("memory_search");
+                    return makeBypassedToolResult("ov_search");
                 }
                 const session = resolvePluginSessionRouting(ctx);
-                return memorySearchOpenViking({
+                return searchOpenViking({
                     query: String(params.query ?? ""),
                     uri: typeof params.uri === "string" ? params.uri : undefined,
                     limit: typeof params.limit === "number" ? params.limit : undefined,
                 }, session.agentId);
             },
-        }), { name: "memory_search" });
+        }), { name: "ov_search" });
         api.registerCommand?.({
             name: "add-resource",
             description: "Add a resource into OpenViking.",
@@ -700,22 +701,22 @@ const contextEnginePlugin = {
             },
         });
         api.registerCommand?.({
-            name: "memory-search",
+            name: "ov-search",
             description: "Search OpenViking resources and skills.",
             acceptsArgs: true,
             handler: async (ctx) => {
                 try {
                     if (isBypassedSession(ctx)) {
-                        const bypassed = makeBypassedToolResult("memory_search");
+                        const bypassed = makeBypassedToolResult("ov_search");
                         return { text: bypassed.content[0].text, details: bypassed.details };
                     }
                     const session = resolvePluginSessionRouting(ctx);
-                    const input = parseMemorySearchCommandArgs(ctx.args ?? "");
-                    const result = await memorySearchOpenViking(input, session.agentId);
+                    const input = parseOVSearchCommandArgs(ctx.args ?? "");
+                    const result = await searchOpenViking(input, session.agentId);
                     return { text: result.content[0].text, details: result.details };
                 }
                 catch (err) {
-                    return { text: `OpenViking memory search failed: ${err instanceof Error ? err.message : String(err)}` };
+                    return { text: `OpenViking search failed: ${err instanceof Error ? err.message : String(err)}` };
                 }
             },
         });
@@ -848,7 +849,7 @@ const contextEnginePlugin = {
         api.registerTool((ctx) => ({
             name: "memory_store",
             label: "Memory Store (OpenViking)",
-            description: "Store text in OpenViking memory pipeline by writing to a session and running memory extraction.",
+            description: "Store text in OpenViking memory pipeline by writing to a session and running memory extraction. Use when the user explicitly asks to remember, save, or store an important long-term fact, preference, project, or decision; automatic capture is threshold/commit dependent.",
             parameters: Type.Object({
                 text: Type.String({ description: "Information to store as memory source text" }),
                 role: Type.Optional(Type.String({ description: "Session role, default user" })),
@@ -914,7 +915,25 @@ const contextEnginePlugin = {
                     }
                     if (memoriesCount === 0) {
                         api.logger.warn(`openviking: memory_store committed but 0 memories extracted (sessionId=${sessionId}). ` +
-                            "Check OpenViking server logs for embedding/extract errors (e.g. 401 API key, or extraction pipeline).");
+                            "No OpenViking-managed long-term memory was created. Check memory.extraction_enabled, VLM configuration/API keys, or whether the text was judged not durable.");
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `Memory extraction completed for session ${sessionId}, but produced 0 memories. ` +
+                                        "No OpenViking-managed long-term memory was stored. Check memory.extraction_enabled, VLM configuration/API keys, or whether the text is durable enough to remember.",
+                                },
+                            ],
+                            details: {
+                                action: "failed",
+                                sessionId,
+                                status: commitResult.status,
+                                error: "no_memories_extracted",
+                                memoriesCount,
+                                archived: commitResult.archived ?? false,
+                                usedTempSession,
+                            },
+                        };
                     }
                     else {
                         api.logger.info?.(`openviking: memory_store committed, memories=${memoriesCount}`);

package/dist/process-manager.js

@@ -10,29 +10,17 @@ export function withTimeout(promise, timeoutMs, timeoutMessage) {
         });
     });
 }
-export async function quickHealthCheck(baseUrl, timeoutMs) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
+export async function quickHealthCheck(client, agentId, timeoutMs) {
     try {
-        const response = await fetch(`${baseUrl}/health`, {
-            method: "GET",
-            signal: controller.signal,
-        });
-        if (!response.ok) {
-            return false;
-        }
-        const body = (await response.json().catch(() => ({})));
-        return body.status === "ok";
+        await client.healthCheck(agentId, timeoutMs);
+        return true;
     }
     catch {
         return false;
     }
-    finally {
-        clearTimeout(timer);
-    }
 }
-export async function quickRecallPrecheck(baseUrl) {
-    const healthOk = await quickHealthCheck(baseUrl, 500);
+export async function quickRecallPrecheck(client, agentId) {
+    const healthOk = await quickHealthCheck(client, agentId, 500);
     if (healthOk) {
         return { ok: true };
     }

package/dist/token-estimator.js

@@ -0,0 +1,51 @@
+function isCjkCodePoint(codePoint) {
+    return ((codePoint >= 0x3400 && codePoint <= 0x4dbf) ||
+        (codePoint >= 0x4e00 && codePoint <= 0x9fff) ||
+        (codePoint >= 0xf900 && codePoint <= 0xfaff) ||
+        (codePoint >= 0x20000 && codePoint <= 0x2ebef) ||
+        (codePoint >= 0x3040 && codePoint <= 0x30ff) ||
+        (codePoint >= 0x31f0 && codePoint <= 0x31ff) ||
+        (codePoint >= 0xac00 && codePoint <= 0xd7af) ||
+        (codePoint >= 0x1100 && codePoint <= 0x11ff) ||
+        (codePoint >= 0x3130 && codePoint <= 0x318f) ||
+        (codePoint >= 0xff00 && codePoint <= 0xffef) ||
+        (codePoint >= 0x3000 && codePoint <= 0x303f));
+}
+function codePointWeight(codePoint) {
+    if (isCjkCodePoint(codePoint)) {
+        return 1.5;
+    }
+    if (codePoint > 0xffff) {
+        return 2;
+    }
+    return 0.25;
+}
+export function estimateTextTokens(text) {
+    if (!text) {
+        return 0;
+    }
+    let weightedTokens = 0;
+    for (const char of text) {
+        weightedTokens += codePointWeight(char.codePointAt(0) ?? 0);
+    }
+    return Math.ceil(weightedTokens);
+}
+export function estimateSerializedTokens(value) {
+    if (value === null || value === undefined) {
+        return 0;
+    }
+    if (typeof value === "string") {
+        return estimateTextTokens(value);
+    }
+    if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+        return estimateTextTokens(String(value));
+    }
+    const serialized = JSON.stringify(value);
+    return estimateTextTokens(serialized ?? "");
+}
+export function estimateAgentMessageTokens(message) {
+    return estimateSerializedTokens(message);
+}
+export function estimateAgentMessagesTokens(messages) {
+    return estimateSerializedTokens(messages);
+}

package/index.ts

@@ -43,6 +43,12 @@ export {
   estimateTokenCount,
   prepareRecallQuery,
 };
+export {
+  estimateAgentMessageTokens,
+  estimateAgentMessagesTokens,
+  estimateSerializedTokens,
+  estimateTextTokens,
+} from "./token-estimator.js";
 export type {
   BuildMemoryLinesOptions,
   BuildMemoryLinesWithBudgetOptions,
@@ -144,7 +150,7 @@ type AddSkillToolInput = {
   timeout?: number;
 };
 
-type MemorySearchInput = {
+type OVSearchInput = {
   query: string;
   uri?: string;
   limit?: number;
@@ -405,13 +411,13 @@ export function parseAddSkillCommandArgs(args: string): AddSkillToolInput {
   };
 }
 
-export function parseMemorySearchCommandArgs(args: string): MemorySearchInput {
+export function parseOVSearchCommandArgs(args: string): OVSearchInput {
   const parsed = parseFlagArgs(args);
-  // `/memory-search` only accepts a single query string, so positional segments are
+  // `/ov-search` only accepts a single query string, so positional segments are
   // always re-joined to preserve unquoted multi-word searches.
   const query = parsed.positionals.join(" ").trim();
   if (!query) {
-    throw new Error('Usage: /memory-search "<query>" [--uri URI] [--limit N]');
+    throw new Error('Usage: /ov-search "<query>" [--uri URI] [--limit N]');
   }
   return {
     query,
@@ -761,7 +767,7 @@ const contextEnginePlugin = {
       };
     };
 
-    const formatMemorySearchRows = (result: FindResult): string[] => {
+    const formatOVSearchRows = (result: FindResult): string[] => {
       const truncateSummary = (value: string, maxChars = 220): string => {
         const collapsed = value.replace(/\s+/g, " ").trim();
         if (collapsed.length <= maxChars) {
@@ -802,7 +808,7 @@ const contextEnginePlugin = {
       ];
     };
 
-    const formatMemorySearchText = (query: string, uri: string | undefined, result: FindResult): string => {
+    const formatOVSearchText = (query: string, uri: string | undefined, result: FindResult): string => {
       if ((result.total ?? 0) <= 0) {
         const scope = uri ? ` under ${uri}` : "";
         return `No OpenViking resource or skill results found for "${query}"${scope}.`;
@@ -811,12 +817,12 @@ const contextEnginePlugin = {
       const lines = [
         `Found ${result.total ?? 0} OpenViking results for "${query}"${scope}`,
         "",
-        ...formatMemorySearchRows(result),
+        ...formatOVSearchRows(result),
       ].filter((line, index, all) => line || (all[index - 1] && all[index + 1]));
       return lines.join("\n");
     };
 
-    const memorySearchOpenViking = async (input: MemorySearchInput, agentId?: string) => {
+    const searchOpenViking = async (input: OVSearchInput, agentId?: string) => {
       const query = input.query.trim();
       if (!query) {
         throw new Error("query is required");
@@ -856,7 +862,7 @@ const contextEnginePlugin = {
         result = mergeFindResults(successful);
       }
       return {
-        content: [{ type: "text" as const, text: formatMemorySearchText(query, input.uri, result) }],
+        content: [{ type: "text" as const, text: formatOVSearchText(query, input.uri, result) }],
         details: {
           action: "searched",
           query,
@@ -935,8 +941,8 @@ const contextEnginePlugin = {
 
     api.registerTool(
       (ctx: ToolContext) => ({
-        name: "memory_search",
-        label: "Memory Search (OpenViking)",
+        name: "ov_search",
+        label: "Search (OpenViking)",
         description:
           "Search OpenViking resources and skills. Use after importing, or when the user asks to search OpenViking resources or skills.",
         parameters: Type.Object({
@@ -946,17 +952,17 @@ const contextEnginePlugin = {
         }),
         async execute(_toolCallId: string, params: Record<string, unknown>) {
           if (isBypassedSession(ctx)) {
-            return makeBypassedToolResult("memory_search");
+            return makeBypassedToolResult("ov_search");
           }
           const session = resolvePluginSessionRouting(ctx);
-          return memorySearchOpenViking({
+          return searchOpenViking({
             query: String((params as { query?: unknown }).query ?? ""),
             uri: typeof params.uri === "string" ? params.uri : undefined,
             limit: typeof params.limit === "number" ? params.limit : undefined,
           }, session.agentId);
         },
       }),
-      { name: "memory_search" },
+      { name: "ov_search" },
     );
 
     api.registerCommand?.({
@@ -1000,21 +1006,21 @@ const contextEnginePlugin = {
     });
 
     api.registerCommand?.({
-      name: "memory-search",
+      name: "ov-search",
       description: "Search OpenViking resources and skills.",
       acceptsArgs: true,
       handler: async (ctx: PluginCommandContext) => {
         try {
           if (isBypassedSession(ctx)) {
-            const bypassed = makeBypassedToolResult("memory_search");
+            const bypassed = makeBypassedToolResult("ov_search");
             return { text: bypassed.content[0]!.text, details: bypassed.details };
           }
           const session = resolvePluginSessionRouting(ctx);
-          const input = parseMemorySearchCommandArgs(ctx.args ?? "");
-          const result = await memorySearchOpenViking(input, session.agentId);
+          const input = parseOVSearchCommandArgs(ctx.args ?? "");
+          const result = await searchOpenViking(input, session.agentId);
           return { text: result.content[0]!.text, details: result.details };
         } catch (err) {
-          return { text: `OpenViking memory search failed: ${err instanceof Error ? err.message : String(err)}` };
+          return { text: `OpenViking search failed: ${err instanceof Error ? err.message : String(err)}` };
         }
       },
     });
@@ -1192,7 +1198,7 @@ const contextEnginePlugin = {
         name: "memory_store",
         label: "Memory Store (OpenViking)",
         description:
-          "Store text in OpenViking memory pipeline by writing to a session and running memory extraction.",
+          "Store text in OpenViking memory pipeline by writing to a session and running memory extraction. Use when the user explicitly asks to remember, save, or store an important long-term fact, preference, project, or decision; automatic capture is threshold/commit dependent.",
         parameters: Type.Object({
           text: Type.String({ description: "Information to store as memory source text" }),
           role: Type.Optional(Type.String({ description: "Session role, default user" })),
@@ -1276,8 +1282,27 @@ const contextEnginePlugin = {
             if (memoriesCount === 0) {
               api.logger.warn(
                 `openviking: memory_store committed but 0 memories extracted (sessionId=${sessionId}). ` +
-                  "Check OpenViking server logs for embedding/extract errors (e.g. 401 API key, or extraction pipeline).",
+                  "No OpenViking-managed long-term memory was created. Check memory.extraction_enabled, VLM configuration/API keys, or whether the text was judged not durable.",
               );
+              return {
+                content: [
+                  {
+                    type: "text",
+                    text:
+                      `Memory extraction completed for session ${sessionId}, but produced 0 memories. ` +
+                      "No OpenViking-managed long-term memory was stored. Check memory.extraction_enabled, VLM configuration/API keys, or whether the text is durable enough to remember.",
+                  },
+                ],
+                details: {
+                  action: "failed",
+                  sessionId,
+                  status: commitResult.status,
+                  error: "no_memories_extracted",
+                  memoriesCount,
+                  archived: commitResult.archived ?? false,
+                  usedTempSession,
+                },
+              };
             } else {
               api.logger.info?.(`openviking: memory_store committed, memories=${memoriesCount}`);
             }

package/install-manifest.json

@@ -15,6 +15,7 @@
       "client.ts",
       "process-manager.ts",
       "memory-ranking.ts",
+      "token-estimator.ts",
       "text-utils.ts",
       "tool-call-id.ts",
       "session-transcript-repair.ts",

package/openclaw.plugin.json

@@ -14,7 +14,7 @@
     "tools": [
       "add_resource",
       "add_skill",
-      "memory_search",
+      "ov_search",
       "memory_recall",
       "memory_store",
       "memory_forget",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openviking/openclaw-plugin",
-  "version": "2026.5.21",
+  "version": "2026.6.2",
   "displayName": "OpenViking",
   "description": "OpenClaw context-engine plugin — OpenViking AI memory, long-term memory, knowledge base, semantic search, RAG, context engine. 长期记忆 · 知识库 · 语义检索 · 上下文引擎",
   "type": "module",

package/process-manager.ts

@@ -1,3 +1,5 @@
+import type { OpenVikingClient } from "./client.js";
+
 export function withTimeout<T>(promise: Promise<T>, timeoutMs: number, timeoutMessage: string): Promise<T> {
   return new Promise((resolve, reject) => {
     const timer = setTimeout(() => reject(new Error(timeoutMessage)), timeoutMs);
@@ -14,30 +16,24 @@ export function withTimeout<T>(promise: Promise<T>, timeoutMs: number, timeoutMe
   });
 }
 
-export async function quickHealthCheck(baseUrl: string, timeoutMs: number): Promise<boolean> {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
+export async function quickHealthCheck(
+  client: OpenVikingClient,
+  agentId: string | undefined,
+  timeoutMs: number,
+): Promise<boolean> {
   try {
-    const response = await fetch(`${baseUrl}/health`, {
-      method: "GET",
-      signal: controller.signal,
-    });
-    if (!response.ok) {
-      return false;
-    }
-    const body = (await response.json().catch(() => ({}))) as { status?: string };
-    return body.status === "ok";
+    await client.healthCheck(agentId, timeoutMs);
+    return true;
   } catch {
     return false;
-  } finally {
-    clearTimeout(timer);
   }
 }
 
 export async function quickRecallPrecheck(
-  baseUrl: string,
+  client: OpenVikingClient,
+  agentId?: string,
 ): Promise<{ ok: true } | { ok: false; reason: string }> {
-  const healthOk = await quickHealthCheck(baseUrl, 500);
+  const healthOk = await quickHealthCheck(client, agentId, 500);
   if (healthOk) {
     return { ok: true };
   }

package/skills/install-openviking-memory/SKILL.md

@@ -413,20 +413,22 @@ Expected output:
 > (CN) 🎉 全部搞定！OpenViking 长期记忆已经接好了。
 >
 > 工作方式：
-> - **每一轮**：你的对话会被自动归档到 OpenViking session 里
-> - **`/compact` 时**：归档消息会被抽取成长期记忆，写到 `~/.openviking/data/` 下
+> - **每一轮**：你的对话会被自动追加到 OpenViking session 里；自动抽取依赖阈值 commit 或 `/compact`
+> - **明确要记住时**：如果你说“记住/保存/存一下”某个长期事实，我会用 `memory_store` 立即提交到记忆管线
+> - **`/compact` 时**：待提交的 session 消息会被抽取成长期记忆，写到 `~/.openviking/data/` 下
 > - **后续会话**：每次回复前我都会自动搜一下相关记忆并带进上下文
 >
-> 想验证一下吗？跟我聊几句包含可记忆事实的话（例如"我的邮箱是 test@example.com"），然后调一下 `/compact`，再开新对话问"我的邮箱是？"，应该就能召回了。
+> 想验证一下吗？可以直接说“记住我的邮箱是 test@example.com”，让我通过 `memory_store` 立即提交；或者先聊几句包含可记忆事实的话，再调一下 `/compact`。之后开新对话问“我的邮箱是？”，应该就能召回了。
 
 > (EN) 🎉 All set! OpenViking long-term memory is connected.
 >
 > How it works:
-> - **Every turn**: our messages are auto-archived into an OpenViking session
-> - **On `/compact`**: archived messages are extracted into long-term memories under `~/.openviking/data/`
+> - **Every turn**: our messages are appended to an OpenViking session; automatic extraction depends on a threshold commit or `/compact`
+> - **Explicit remember requests**: if you ask me to remember/save/store a long-term fact, I can use `memory_store` to commit it immediately
+> - **On `/compact`**: pending session messages are extracted into long-term memories under `~/.openviking/data/`
 > - **Future sessions**: relevant memories are auto-retrieved and injected before my replies
 >
-> Want to verify? Tell me a few facts (e.g. "my email is test@example.com"), run `/compact`, then start a new chat and ask "what's my email?" — it should recall.
+> Want to verify? Say "remember my email is test@example.com" so I can commit it via `memory_store`, or tell me a few memory-worthy facts and run `/compact`. Then start a new chat and ask "what's my email?" — it should recall.
 
 ---
 
@@ -434,15 +436,25 @@ Expected output:
 
 ## How It Works
 
-The context-engine pipeline has three distinct stages — keep them apart, especially when telling users when memories actually appear in `~/.openviking/data/`:
+The context-engine pipeline has three distinct stages plus one explicit write path — keep them apart, especially when telling users when memories actually appear in `~/.openviking/data/`:
 
-- **Archive / capture (context-engine `afterTurn`)**: at the end of a user turn, the plugin commits user/assistant messages to the OpenViking session via `POST /api/v1/sessions/.../messages`. This is **archive only** — no memory extraction yet. You'll see session message counts grow on the server, but no new files under `viking://user/.../memories/`.
-- **Memory extraction (on `/compact`)**: memory extraction runs when the user invokes OpenClaw's `/compact` command. The server-side extraction pipeline reads the archived session and writes new memories. The plugin's `after_compaction` hook is currently reserved; the extraction itself is driven by the server. **No `/compact`, no new memory files.**
+- **Archive / capture (context-engine `afterTurn`)**: at the end of a user turn, the plugin appends user/assistant messages to the OpenViking session via `POST /api/v1/sessions/.../messages`. This is **session capture only** unless `pending_tokens` crosses `commitTokenThreshold`; below the threshold, no memory extraction runs yet. You'll see session message counts grow on the server, but no new files under `viking://user/.../memories/`.
+- **Memory extraction (threshold commit or `/compact`)**: memory extraction runs after a session commit. The commit can be triggered asynchronously when `afterTurn` crosses `commitTokenThreshold`, synchronously when the user invokes OpenClaw's `/compact` command, or explicitly by `memory_store`. The server-side extraction pipeline reads the archived session and writes new memories.
   - `captureMode: "semantic"` (default): server extraction pipeline filters all qualifying text.
   - `captureMode: "keyword"`: only text matching trigger words (e.g. "remember", "preference") is considered.
 - **Auto-Recall (context-engine `assemble()`)**: before prompt context is assembled, the plugin queries OpenViking for relevant memories and injects them into context. Recall works even when there are no extracted memories yet — you just won't see anything come back.
 
-**Practical implication for testing**: if you write down a fact and immediately try to recall it without `/compact`, the plugin will only retrieve it as recent session context (archived messages), not as a long-term memory. To verify long-term memory cross-session, you must run `/compact` first.
+**Practical implication for testing**: if you write down a short fact and immediately try to recall it without a threshold commit, `/compact`, or `memory_store`, the plugin may only retrieve it as recent session context, not as a long-term memory. To verify long-term memory cross-session deterministically, run `/compact` or use `memory_store` for the fact being tested.
+
+### Explicit long-term memory writes
+
+Auto-capture is best-effort and commit-dependent. When the user explicitly says to remember, save, or store an important long-term fact, preference, project, or decision, the agent should call `memory_store` instead of waiting for ordinary auto-capture.
+
+Use `memory_store` as the integration-side reliable path for durable-memory intent:
+
+- It writes the supplied text into an OpenViking session and calls `commit(wait=true)`.
+- It complements auto-capture; it does not replace normal session capture.
+- If it commits but extracts 0 memories, the explicit path has done its job. Treat that as a server-side extraction/model/configuration issue and check OpenViking logs.
 
 ## Available Tools
 
@@ -467,6 +479,8 @@ Example: user asks "What programming language did I say I like?"
 | `role` | No | Session role (default `user`) |
 | `sessionId` | No | Existing OpenViking session ID |
 
+Use this when the user explicitly asks to remember/save/store a long-term fact, preference, project, or decision.
+
 Example: user says "Remember my email is xxx@example.com".
 
 ### `memory_forget` — Delete Memories
@@ -495,7 +509,7 @@ These are the keys under `plugins.entries.openviking.config` in `openclaw.json`.
 | `userId` | — | Required when `apiKey` is a root key. |
 | `targetUri` | `viking://user/memories` | Default search scope URI. |
 | `timeoutMs` | (plugin default) | HTTP timeout for OpenViking calls. |
-| `autoCapture` | `true` | Auto-archive turn messages to OpenViking session at `afterTurn` (extraction itself runs on `/compact`, not here). |
+| `autoCapture` | `true` | Auto-append turn messages to the OpenViking session at `afterTurn`; extraction runs only after a threshold commit, `/compact`, or explicit `memory_store`. |
 | `captureMode` | `"semantic"` | Filter mode used by the server-side extraction pipeline: `semantic` or `keyword`. |
 | `captureMaxLength` | `24000` | Max text length per archived turn. |
 | `autoRecall` | `true` | Auto-recall and inject memories before reply. |

package/token-estimator.ts

@@ -0,0 +1,65 @@
+type TokenCountableAgentMessage = {
+  role?: string;
+  content?: unknown;
+};
+
+function isCjkCodePoint(codePoint: number): boolean {
+  return (
+    (codePoint >= 0x3400 && codePoint <= 0x4dbf) ||
+    (codePoint >= 0x4e00 && codePoint <= 0x9fff) ||
+    (codePoint >= 0xf900 && codePoint <= 0xfaff) ||
+    (codePoint >= 0x20000 && codePoint <= 0x2ebef) ||
+    (codePoint >= 0x3040 && codePoint <= 0x30ff) ||
+    (codePoint >= 0x31f0 && codePoint <= 0x31ff) ||
+    (codePoint >= 0xac00 && codePoint <= 0xd7af) ||
+    (codePoint >= 0x1100 && codePoint <= 0x11ff) ||
+    (codePoint >= 0x3130 && codePoint <= 0x318f) ||
+    (codePoint >= 0xff00 && codePoint <= 0xffef) ||
+    (codePoint >= 0x3000 && codePoint <= 0x303f)
+  );
+}
+
+function codePointWeight(codePoint: number): number {
+  if (isCjkCodePoint(codePoint)) {
+    return 1.5;
+  }
+  if (codePoint > 0xffff) {
+    return 2;
+  }
+  return 0.25;
+}
+
+export function estimateTextTokens(text: string | null | undefined): number {
+  if (!text) {
+    return 0;
+  }
+
+  let weightedTokens = 0;
+  for (const char of text) {
+    weightedTokens += codePointWeight(char.codePointAt(0) ?? 0);
+  }
+  return Math.ceil(weightedTokens);
+}
+
+export function estimateSerializedTokens(value: unknown): number {
+  if (value === null || value === undefined) {
+    return 0;
+  }
+  if (typeof value === "string") {
+    return estimateTextTokens(value);
+  }
+  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+    return estimateTextTokens(String(value));
+  }
+
+  const serialized = JSON.stringify(value);
+  return estimateTextTokens(serialized ?? "");
+}
+
+export function estimateAgentMessageTokens(message: TokenCountableAgentMessage): number {
+  return estimateSerializedTokens(message);
+}
+
+export function estimateAgentMessagesTokens(messages: TokenCountableAgentMessage[]): number {
+  return estimateSerializedTokens(messages);
+}