feat(openviking-memory): add memory_recall tool, rename memory_save_turn, translate docs to English

Add recallMemories method to OpenVikingClient (delegates to searchMemories)

Register memory_recall tool for system-triggered context injection

Rename memory_save_conversation tool to memory_save_turn

Rename saveConversation to saveTurn in client interface and implementation

Translate all tool titles, descriptions, and parameter docs from Chinese to English

Mark system-only tools (memory_recall, memory_save_turn) with empty activation keywords

Update plugin-tools.ts constants to reference memory_recall and memory_save_turn

Update Readme with memory_recall, memory_save_turn, session memory processing rules, and system-triggered tool usage notes

Author: xiaobin83

apps/stage-tamagotchi/src/main/services/airi/plugins/examples/openviking-memory/docs/Readme.zh-CN.md

@@ -51,9 +51,21 @@
 
 - **读取记忆**（`memory_read`）：根据 URI 读取一条记忆的完整内容
 - **保存记忆**（`memory_save`）：将重要信息保存到长期记忆
-- **保存对话记录**（`memory_save_conversation`）：将一轮对话（用户消息 + 助手回复 + 工具调用）保存到长期记忆
+- **保存对话记录**（`memory_save_turn`）：将一轮对话（用户消息 + 助手回复 + 工具调用）保存到长期记忆。此工具由系统自动触发，AI 助手不应主动调用。
+- **召回记忆**（`memory_recall`）：自动召回与当前对话相关的长期记忆，用于上下文注入。此工具由系统自动触发，AI 助手不应主动调用。
 - **删除记忆**（`memory_delete`）：删除指定的记忆条目
 
+> `memory_recall` 和 `memory_save_turn` 为系统级工具，由框架在对话处理流程中自动调用，用于上下文注入和对话持久化。AI 助手不会在工具选择列表中看到它们，开发者也不应手动调用。
+
+### Session 记忆处理
+
+对话通过 `memory_save_turn` 保存到 Session 后，系统会按以下规则决定是否将对话内容转化为可检索的记忆：
+
+- **短对话**（累计 pending tokens < 20,000）：仅保存到 Session，不参与记忆搜索
+- **长对话**（累计 pending tokens ≥ 20,000）：自动提交并做 embedding 处理，之后可通过记忆注入（`memory_recall`）或 Agent 主动搜索（`memory_search`）找到
+
+例如，一个持续数小时的长对话（如聊了一整晚）达到阈值后会被 embedding，后续用户提问时系统会自动召回相关记忆片段作为上下文注入。
+
 ## 安装
 
 ### 前提条件
@@ -119,11 +131,12 @@
 
 加载成功后，AIRI 将获得以下工具能力：
 
-- `memory_search` — 搜索长期记忆
-- `memory_read` — 根据 URI 读取记忆完整内容
-- `memory_save` — 保存记忆
-- `memory_save_conversation` — 保存对话记录
-- `memory_delete` — 删除记忆
+- `memory_search` — 搜索长期记忆（Agent 主动调用）
+- `memory_read` — 根据 URI 读取记忆完整内容（Agent 主动调用）
+- `memory_save` — 保存记忆（Agent 主动调用）
+- `memory_save_turn` — 保存对话记录（系统自动触发）
+- `memory_recall` — 召回记忆（系统自动触发）
+- `memory_delete` — 删除记忆（Agent 主动调用）
 
 ## 开发
 

apps/stage-tamagotchi/src/main/services/airi/plugins/examples/openviking-memory/src/index.ts

@@ -27,17 +27,17 @@ export async function setupModules({ apis }: ContextInit): Promise<void> {
   await apis.tools.register({
     tool: {
       id: 'memory_search',
-      title: '搜索记忆',
-      description: '搜索长期记忆中的相关信息',
+      title: 'Search Memory',
+      description: 'Retrieve specific memory entries from long-term storage by contextual keywords, time references, or event descriptions. Use this when you need to recall factual details (what happened, how something was done), temporal information (specific dates, years, months, days, weekends, weeks, or relative timeframes like "last week" or "yesterday"), or scheduled events (appointments, arrangements, calendar entries, or planned activities). Returns matching memory entries with relevance scores and metadata.',
       activation: {
-        keywords: ['记忆', '回忆', '搜索'],
+        keywords: ['search', 'find', 'recall', 'look up', 'what', 'when', 'did', 'remember', 'tell me about'],
         patterns: [],
       },
       parameters: {
         type: 'object',
         properties: {
-          query: { type: 'string', description: '搜索查询' },
-          limit: { type: 'number', description: '返回结果数量', default: 5 },
+          query: { type: 'string', description: 'Natural language search query describing the information to recall, including keywords, time references, event descriptions, or contextual details' },
+          limit: { type: 'number', description: 'Maximum number of memory results to return', default: 5 },
         },
         required: ['query'],
       },
@@ -52,16 +52,16 @@ export async function setupModules({ apis }: ContextInit): Promise<void> {
   await apis.tools.register({
     tool: {
       id: 'memory_read',
-      title: '读取记忆',
-      description: '根据 URI 读取一条记忆的完整内容',
+      title: 'Read Memory',
+      description: 'Retrieve the full detailed content of a specific memory entry identified by its URI. Use this when you need to access complete context and details of a previously identified memory item, such as viewing the entire content found through memory_search. This provides the full text and metadata of a single memory entry, as opposed to performing a broader search across memories.',
       activation: {
-        keywords: ['读取', '查看', '阅读'],
+        keywords: ['read', 'show', 'view', 'get details', 'open', 'display', 'see'],
         patterns: [],
       },
       parameters: {
         type: 'object',
         properties: {
-          uri: { type: 'string', description: '记忆的 URI（如 viking://user/default/...）' },
+          uri: { type: 'string', description: 'The URI of the memory entry to read (e.g. viking://user/default/...). Obtain this from memory_search results.' },
         },
         required: ['uri'],
       },
@@ -76,19 +76,19 @@ export async function setupModules({ apis }: ContextInit): Promise<void> {
     tool: {
       id: 'memory_save',
       title: '保存记忆',
-      description: '保存一条重要信息到长期记忆',
+      description: 'Store a piece of important information into long-term memory for future recall. Use this when you need to remember factual details, user preferences, key decisions, follow-up tasks, or any information that should be persisted beyond the current conversation. The saved content can later be retrieved using memory_search. Optionally attach tags for better organization and retrieval.',
       activation: {
-        keywords: ['记住', '保存', '记忆'],
+        keywords: ['save', 'remember', 'store', 'keep', 'record', 'note', 'add', 'learn'],
         patterns: [],
       },
       parameters: {
         type: 'object',
         properties: {
-          content: { type: 'string', description: '要记忆的内容' },
+          content: { type: 'string', description: 'The information content to store in long-term memory' },
           tags: {
             type: 'array',
             items: { type: 'string' },
-            description: '标签',
+            description: 'Optional tags for categorizing and organizing memory entries for easier retrieval',
           },
         },
         required: ['content'],
@@ -102,44 +102,69 @@ export async function setupModules({ apis }: ContextInit): Promise<void> {
 
   await apis.tools.register({
     tool: {
-      id: 'memory_save_conversation',
-      title: '保存对话记录',
-      description: '将一轮对话（用户消息 + 助手回复 + 工具调用）保存到长期记忆',
+      id: 'memory_recall',
+      title: 'Recall Memory',
+      description: 'Automatically recall long-term memories relevant to the current conversation for context injection. NOTICE: This tool is triggered by the system only and should not be invoked by the AI assistant.',
       activation: {
-        keywords: ['保存对话', '记录对话', '记住对话', '保存聊天', '保存'],
+        keywords: [],
         patterns: [],
       },
       parameters: {
         type: 'object',
         properties: {
-          sessionId: { type: 'string', description: '对话会话 ID，同一对话应使用相同 ID。首次不传会自动创建' },
-          userMessage: { type: 'string', description: '用户消息' },
-          assistantResponse: { type: 'string', description: '助手回复' },
-          toolCalls: { type: 'object', description: '工具调用记录' },
-          timestamp: { type: 'string', description: '时间戳' },
+          query: { type: 'string', description: 'Search query describing the context to recall from long-term memory' },
+          limit: { type: 'number', description: 'Maximum number of memory results to return', default: 5 },
+        },
+        required: ['query'],
+      },
+    },
+    execute: async (input: unknown) => {
+      const { query, limit } = input as { query: string, limit?: number }
+      const results = await client!.recallMemories(query, limit)
+      return { results }
+    },
+  })
+
+  await apis.tools.register({
+    tool: {
+      id: 'memory_save_turn',
+      title: 'Save Conversation Turn',
+      description: 'Save a conversation turn (user message + assistant response + tool calls) into long-term memory. NOTICE: This tool is triggered by the system only and should not be invoked by the AI assistant.',
+      activation: {
+        keywords: [],
+        patterns: [],
+      },
+      parameters: {
+        type: 'object',
+        properties: {
+          sessionId: { type: 'string', description: 'Conversation session ID. Use the same ID for the same conversation; auto-created if not provided' },
+          userMessage: { type: 'string', description: 'The user message content' },
+          assistantResponse: { type: 'string', description: 'The assistant response content' },
+          toolCalls: { type: 'object', description: 'Record of tool calls made during the conversation turn' },
+          timestamp: { type: 'string', description: 'ISO 8601 timestamp of the conversation turn' },
         },
         required: ['userMessage', 'assistantResponse', 'timestamp'],
       },
     },
     execute: async (input: unknown) => {
       const turn = input as { sessionId?: string, userMessage: string, assistantResponse: string, toolCalls?: unknown[], timestamp: string }
-      return await client!.saveConversation(turn)
+      return await client!.saveTurn(turn)
     },
   })
 
   await apis.tools.register({
     tool: {
       id: 'memory_delete',
-      title: '删除记忆',
-      description: '删除一条记忆',
+      title: 'Delete Memory',
+      description: 'Permanently and irreversibly remove a specific memory entry from long-term storage. Use this only when you have explicit intent to discard particular information. This action cannot be undone — the deleted memory entry and all its associated data will be erased permanently.',
       activation: {
-        keywords: ['删除', '移除', '清除'],
+        keywords: ['delete', 'remove', 'erase', 'forget', 'discard', 'clear'],
         patterns: [],
       },
       parameters: {
         type: 'object',
         properties: {
-          id: { type: 'string', description: '要删除的记忆 ID' },
+          id: { type: 'string', description: 'The unique identifier of the memory entry to permanently delete' },
         },
         required: ['id'],
       },

apps/stage-tamagotchi/src/main/services/airi/plugins/examples/openviking-memory/src/openviking.ts

@@ -36,11 +36,12 @@ export interface OpenVikingClientConfig {
 
 export interface OpenVikingClient {
   searchMemories: (query: string, limit?: number) => Promise<Record<string, unknown>[]>
+  recallMemories: (query: string, limit?: number) => Promise<Record<string, unknown>[]>
   readMemory: (uri: string) => Promise<{ uri: string, content: string }>
   addSessionMessage: (sessionId: string, role: string, content: string, createdAt?: string) => Promise<void>
   getSession: (sessionId: string) => Promise<SessionInfo>
   commitSession: (sessionId: string, keepRecentCount?: number) => Promise<void>
-  saveConversation: (conversation: ConversationTurn) => Promise<ConversationSaveResult>
+  saveTurn: (turn: ConversationTurn) => Promise<ConversationSaveResult>
   saveMemory: (content: string, tags?: string[]) => Promise<{ id: string }>
   deleteMemory: (id: string) => Promise<void>
   healthCheck: () => Promise<boolean>
@@ -132,6 +133,10 @@ export function createOpenVikingClient(config: OpenVikingClientConfig): OpenViki
       return data.result?.memories ?? []
     },
 
+    async recallMemories(query: string, limit = 5): Promise<Record<string, unknown>[]> {
+      return await this.searchMemories(query, limit)
+    },
+
     async readMemory(uri: string): Promise<{ uri: string, content: string }> {
       const params = new URLSearchParams({ uri })
       const response = await apiFetch(`/api/v1/content/read?${params}`, {
@@ -199,11 +204,11 @@ export function createOpenVikingClient(config: OpenVikingClientConfig): OpenViki
       }
     },
 
-    async saveConversation(conversation: ConversationTurn): Promise<ConversationSaveResult> {
-      const sessionId = conversation.sessionId || crypto.randomUUID()
+    async saveTurn(turn: ConversationTurn): Promise<ConversationSaveResult> {
+      const sessionId = turn.sessionId || crypto.randomUUID()
 
-      await this.addSessionMessage(sessionId, 'user', conversation.userMessage || '(empty)', conversation.timestamp)
-      await this.addSessionMessage(sessionId, 'assistant', conversation.assistantResponse || '(empty)', conversation.timestamp)
+      await this.addSessionMessage(sessionId, 'user', turn.userMessage || '(empty)', turn.timestamp)
+      await this.addSessionMessage(sessionId, 'assistant', turn.assistantResponse || '(empty)', turn.timestamp)
 
       let committed = false
       try {

apps/stage-tamagotchi/src/renderer/stores/plugin-tools.ts

@@ -14,8 +14,8 @@ import { electronPluginList } from '../../shared/eventa/plugin/host'
 import { electronPluginInvokeTool, electronPluginListXsaiTools } from '../../shared/eventa/plugin/tools'
 
 const PLUGIN_CONTEXT_ID_PREFIX = 'system:plugin:'
-const MEMORY_SAVE_CONVERSATION_TOOL = 'memory_save_conversation'
-const MEMORY_SEARCH_TOOL = 'memory_search'
+const MEMORY_SAVE_TURN = 'memory_save_turn'
+const MEMORY_RECALL_TOOL = 'memory_recall'
 const MEMORY_CONTEXT_TIMEOUT_MS = 3_000
 
 function generateId(): string {
@@ -86,10 +86,10 @@ export const useTamagotchiPluginToolsStore = defineStore('tamagotchi-plugin-tool
           pluginsWithMemorySaveTool.clear()
           pluginsWithMemorySearchTool.clear()
           for (const tool of definitions.tools) {
-            if (tool.name === MEMORY_SAVE_CONVERSATION_TOOL) {
+            if (tool.name === MEMORY_SAVE_TURN) {
               pluginsWithMemorySaveTool.add(tool.ownerPluginId)
             }
-            if (tool.name === MEMORY_SEARCH_TOOL) {
+            if (tool.name === MEMORY_RECALL_TOOL) {
               pluginsWithMemorySearchTool.add(tool.ownerPluginId)
             }
           }
@@ -141,7 +141,7 @@ export const useTamagotchiPluginToolsStore = defineStore('tamagotchi-plugin-tool
       loadedPlugins.map(async (plugin) => {
         const result = await invokePluginTool({
           ownerPluginId: plugin.name,
-          name: MEMORY_SEARCH_TOOL,
+          name: MEMORY_RECALL_TOOL,
           input: { query: sendingMessage },
         }, { signal: AbortSignal.timeout(MEMORY_CONTEXT_TIMEOUT_MS) })
 
@@ -220,7 +220,7 @@ export const useTamagotchiPluginToolsStore = defineStore('tamagotchi-plugin-tool
         for (const plugin of loadedPlugins) {
           invokePluginTool({
             ownerPluginId: plugin.name,
-            name: MEMORY_SAVE_CONVERSATION_TOOL,
+            name: MEMORY_SAVE_TURN,
             input: turn,
           }).catch((err: unknown) => console.warn(`[plugin-tools] failed to save turn to plugin "${plugin.name}"`, err))
         }