Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat:Add OpenCode memory plugin example (#569)

李小默mocae2c37c0a09
diff --git a/README.md b/README.md
index f531ec098..b972c9d97 100644
--- a/README.md
+++ b/README.md
@@ -491,6 +491,8 @@ After integrating OpenViking:
👉 **[View: OpenClaw Memory Plugin](examples/openclaw-memory-plugin/README.md)**
+👉 **[View: OpenCode Memory Plugin Example](examples/opencode-memory-plugin/README.md)**
+
--
## Core Concepts
diff --git a/README_CN.md b/README_CN.md
index 116708599..8a34c4761 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -487,6 +487,8 @@ ov chat
👉 **[查看:OpenClaw 记忆插件](examples/openclaw-memory-plugin/README.md)**
+👉 **[查看:OpenCode 记忆插件示例](examples/opencode-memory-plugin/README.md)**
+
## VikingBot 部署详情
OpenViking 有一个类似 nanobot 的机器人用于交互工作,现已可用。
diff --git a/examples/opencode-memory-plugin/.gitignore b/examples/opencode-memory-plugin/.gitignore
new file mode 100644
index 000000000..c717c024b
--- /dev/null
+++ b/examples/opencode-memory-plugin/.gitignore
@@ -0,0 +1,5 @@
+.DS_Store
+openviking-config.json
+openviking-memory.log
+openviking-session-map.json
+*.corrupted.*
diff --git a/examples/opencode-memory-plugin/INSTALL-ZH.md b/examples/opencode-memory-plugin/INSTALL-ZH.md
new file mode 100644
index 000000000..216d2916c
--- /dev/null
+++ b/examples/opencode-memory-plugin/INSTALL-ZH.md
@@ -0,0 +1,236 @@
+# 为 OpenCode 安装 OpenViking Memory Plugin
+
+这个示例把 OpenViking 暴露为 OpenCode 可直接调用的记忆工具,并自动把当前对话同步到 OpenViking Session 中。
+
+安装完成后,你可以在 OpenCode 中使用这些工具:
+
+- `memsearch`
+- `memread`
+- `membrowse`
+- `memcommit`
+
+---
+
+## 机制说明
+
+这个示例使用的是 OpenCode 的 tool 机制,把 OpenViking 能力显式暴露成 Agent 可调用的工具。
+
+更具体一点:
+
+- Agent 会看到 `memsearch`、`memread`、`membrowse`、`memcommit` 这些显式工具
+- 只有在 Agent 主动调用这些工具时,OpenViking 的内容才会被读取回来
+- 插件还会在后台把 OpenCode session 映射到 OpenViking session,并在合适的时候触发记忆提取
+
+这个示例的重点是显式 memory 访问、类文件系统浏览,以及会话到长期记忆的自动同步。
+
+---
+
+## 前置条件
+
+你需要先准备:
+
+- 已安装 OpenCode
+- 已启动 OpenViking HTTP Server
+- 可用的 OpenViking API Key(如果服务端启用了认证)
+
+建议先确认 OpenViking 服务正常运行:
+
+```bash
+openviking-server --config ~/.openviking/ov.conf
+```
+
+如果你已经在后台启动了服务,也可以直接检查健康状态:
+
+```bash
+curl http://localhost:1933/health
+```
+
+---
+
+## 安装步骤
+
+OpenCode 官方文档更推荐把插件放在:
+
+```bash
+~/.config/opencode/plugins
+```
+
+### Step 1: 创建插件目录
+
+```bash
+mkdir -p ~/.config/opencode/plugins
+```
+
+### Step 2: 复制示例文件
+
+在 OpenViking 仓库根目录执行:
+
+```bash
+cp examples/opencode-memory-plugin/openviking-memory.ts ~/.config/opencode/plugins/openviking-memory.ts
+cp examples/opencode-memory-plugin/openviking-config.example.json ~/.config/opencode/plugins/openviking-config.json
+cp examples/opencode-memory-plugin/.gitignore ~/.config/opencode/plugins/.gitignore
+```
+
+复制后,插件目录里应该至少有这些文件:
+
+```text
+~/.config/opencode/plugins/
+├── .gitignore
+├── openviking-config.json
+└── openviking-memory.ts
+```
+
+### Step 3: 配置插件
+
+编辑:
+
+```bash
+~/.config/opencode/plugins/openviking-config.json
+```
+
+示例配置:
+
+```json
+{
+ "endpoint": "http://localhost:1933",
+ "apiKey": "",
+ "enabled": true,
+ "timeoutMs": 30000,
+ "autoCommit": {
+ "enabled": true,
+ "intervalMinutes": 10
+ }
+}
+```
+
+字段说明:
+
+- `endpoint`: OpenViking 服务地址
+- `apiKey`: 可留空,推荐用环境变量提供
+- `enabled`: 是否启用插件
+- `timeoutMs`: 普通请求超时时间
+- `autoCommit.intervalMinutes`: 自动提交 session 的周期
+
+### Step 3.5: 关于插件注册
+
+这个插件不需要额外写进 `~/.config/opencode/opencode.json`。
+
+原因是 OpenCode 会自动扫描 `~/.config/opencode/plugins/` 下面的一级 `*.ts` / `*.js` 文件,`openviking-memory.ts` 放在这个目录顶层即可被发现。
+
+### Step 4: 配置 API Key
+
+推荐使用环境变量,不要把真实 key 写进配置文件:
+
+```bash
+export OPENVIKING_API_KEY="your-api-key-here"
+```
+
+如果你使用 `zsh`,可以把它写进 `~/.zshrc`:
+
+```bash
+echo 'export OPENVIKING_API_KEY="your-api-key-here"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+---
+
+## 启动与验证
+
+配置完成后,正常启动 OpenCode 即可。
+
+插件初始化后会:
+
+- 对 OpenViking 做一次 health check
+- 为每个 OpenCode session 自动建立对应的 OpenViking session
+- 自动把用户消息和 assistant 消息写入 OpenViking
+- 按周期触发后台 `commit`
+
+你可以在会话里尝试:
+
+```text
+请用 memsearch 搜索我之前的偏好
+```
+
+或者手动触发一次记忆提取:
+
+```text
+请调用 memcommit
+```
+
+---
+
+## 运行时文件
+
+插件运行后,会在插件目录里生成这些本地文件:
+
+- `~/.config/opencode/plugins/openviking-config.json`
+- `~/.config/opencode/plugins/openviking-memory.log`
+- `~/.config/opencode/plugins/openviking-session-map.json`
+
+这些文件都是运行时产物,不建议提交到版本库。示例里的 `.gitignore` 已经帮你排除了它们。
+
+如果你明确希望按工作区隔离插件,也可以把这三个文件和 `openviking-memory.ts` 一起放在工作区本地插件目录里。当前实现会把配置和运行时文件统一保存在“插件文件所在目录”。
+
+---
+
+## 常见问题
+
+### 1. 插件没有生效
+
+先确认文件位置正确:
+
+```bash
+ls ~/.config/opencode/plugins/
+```
+
+至少要能看到:
+
+- `openviking-memory.ts`
+- `openviking-config.json`
+
+### 2. `Authentication failed`
+
+通常是 API Key 配置不对。优先检查:
+
+- `OPENVIKING_API_KEY` 是否已设置
+- 服务端是否启用了认证
+- `endpoint` 是否连到了正确的 OpenViking 服务
+
+### 3. `Service unavailable`
+
+说明插件连不上 OpenViking 服务。检查:
+
+```bash
+curl http://localhost:1933/health
+```
+
+如果失败,先启动:
+
+```bash
+openviking-server --config ~/.openviking/ov.conf
+```
+
+### 4. `memcommit` 很慢或经常超时
+
+这个示例已经改成了后台 commit task 模式。一般情况下,即使记忆提取比较慢,也不应该再出现“每分钟同步重试一次”的风暴。
+
+如果你仍然觉得慢,优先检查的是:
+
+- OpenViking 服务端的模型配置
+- 服务端所在机器的资源是否吃满
+- `openviking-memory.log` 里是否有持续的 task failure
+
+### 5. 没有抽出任何 memory
+
+通常不是插件没工作,而是服务端提取条件不满足。优先检查:
+
+- OpenViking 的 `vlm` 和 `embedding` 是否已正确配置
+- 当前对话里是否真的有适合沉淀为 memory 的内容
+
+---
+
+## 相关文件
+
+- [README.md](./README.md): English overview
+- [openviking-memory.ts](./openviking-memory.ts): plugin implementation
+- [openviking-config.example.json](./openviking-config.example.json): config template
diff --git a/examples/opencode-memory-plugin/README.md b/examples/opencode-memory-plugin/README.md
new file mode 100644
index 000000000..f2d373cd0
--- /dev/null
+++ b/examples/opencode-memory-plugin/README.md
@@ -0,0 +1,196 @@
+# OpenViking Memory Plugin for OpenCode
+
+OpenCode plugin example that exposes OpenViking memories as explicit tools and automatically syncs conversation sessions into OpenViking.
+
+Chinese install guide: [INSTALL-ZH.md](./INSTALL-ZH.md)
+
+## Mechanism
+
+This example uses OpenCode's tool mechanism to expose OpenViking capabilities as explicit agent-callable tools.
+
+In practice, that means:
+
+- the agent sees concrete tools and decides when to call them
+- OpenViking data is fetched on demand through tool execution instead of being pre-injected into every prompt
+- the plugin also keeps an OpenViking session in sync with the OpenCode conversation and triggers background memory extraction with `memcommit`
+
+This example focuses on explicit memory access, filesystem-style browsing, and session-to-memory synchronization inside OpenCode.
+
+## What It Does
+
+- Exposes four memory tools for OpenCode agents:
+ - `memsearch`
+ - `memread`
+ - `membrowse`
+ - `memcommit`
+- Automatically maps each OpenCode session to an OpenViking session
+- Streams user and assistant messages into OpenViking
+- Uses background `commit` tasks to avoid repeated synchronous timeout failures
+- Persists local runtime state for reconnect and recovery
+
+## Files
+
+This example contains:
+
+- `openviking-memory.ts`: the plugin implementation used by OpenCode
+- `openviking-config.example.json`: template config
+- `.gitignore`: ignores local runtime files after you copy the example into a workspace
+
+## Prerequisites
+
+- OpenCode
+- OpenViking HTTP Server
+- A valid OpenViking API key if your server requires authentication
+
+Start the server first if it is not already running:
+
+```bash
+openviking-server --config ~/.openviking/ov.conf
+```
+
+## Install Into OpenCode
+
+Recommended location from the OpenCode docs:
+
+```bash
+~/.config/opencode/plugins
+```
+
+Install with:
+
+```bash
+mkdir -p ~/.config/opencode/plugins
+cp examples/opencode-memory-plugin/openviking-memory.ts ~/.config/opencode/plugins/openviking-memory.ts
+cp examples/opencode-memory-plugin/openviking-config.example.json ~/.config/opencode/plugins/openviking-config.json
+cp examples/opencode-memory-plugin/.gitignore ~/.config/opencode/plugins/.gitignore
+```
+
+Then edit `~/.config/opencode/plugins/openviking-config.json`.
+
+OpenCode auto-discovers first-level `*.ts` and `*.js` files under `~/.config/opencode/plugins`, so no explicit `plugin` entry is required in `~/.config/opencode/opencode.json`.
+
+This plugin also works if you intentionally place it in a workspace-local plugin directory, because it stores config and runtime files next to the plugin file itself.
+
+Recommended: provide the API key via environment variable instead of writing it into the config file:
+
+```bash
+export OPENVIKING_API_KEY="your-api-key-here"
+```
+
+## Configuration
+
+Example config:
+
+```json
+{
+ "endpoint": "http://localhost:1933",
+ "apiKey": "",
+ "enabled": true,
+ "timeoutMs": 30000,
+ "autoCommit": {
+ "enabled": true,
+ "intervalMinutes": 10
+ }
+}
+```
+
+The environment variable `OPENVIKING_API_KEY` takes precedence over the config file.
+
+## Runtime Files
+
+After installation, the plugin creates these local files next to the plugin file:
+
+- `openviking-config.json`
+- `openviking-memory.log`
+- `openviking-session-map.json`
+
+These are runtime artifacts and should not be committed.
+
+## Tools
+
+### `memsearch`
+
+Unified search across memories, resources, and skills.
+
+Parameters:
+
+- `query`: search query
+- `target_uri?`: narrow search to a URI prefix such as `viking://user/memories/`
+- `mode?`: `auto | fast | deep`
+- `limit?`: max results
+- `score_threshold?`: optional minimum score
+
+### `memread`
+
+Read content from a specific `viking://` URI.
+
+Parameters:
+
+- `uri`: target URI
+- `level?`: `auto | abstract | overview | read`
+
+### `membrowse`
+
+Browse the OpenViking filesystem layout.
+
+Parameters:
+
+- `uri`: target URI
+- `view?`: `list | tree | stat`
+- `recursive?`: only for `view: "list"`
+- `simple?`: only for `view: "list"`
+
+### `memcommit`
+
+Trigger immediate memory extraction for the current session.
+
+Parameters:
+
+- `session_id?`: optional explicit OpenViking session ID
+
+Returns background task progress or completion details, including `task_id`, `memories_extracted`, and `archived`.
+
+## Usage Examples
+
+Search and then read:
+
+```typescript
+const results = await memsearch({
+ query: "user coding preferences",
+ target_uri: "viking://user/memories/",
+ mode: "auto"
+})
+
+const content = await memread({
+ uri: results[0].uri,
+ level: "auto"
+})
+```
+
+Browse first:
+
+```typescript
+const tree = await membrowse({
+ uri: "viking://resources/",
+ view: "tree"
+})
+```
+
+Force a mid-session commit:
+
+```typescript
+const result = await memcommit({})
+```
+
+## Notes for Reviewers
+
+- The plugin is designed to run as a first-level `*.ts` file in the OpenCode plugins directory
+- It intentionally keeps runtime config, logs, and session maps outside the repository example
+- It uses OpenViking background commit tasks to avoid repeated timeout/retry loops during long memory extraction
+
+## Troubleshooting
+
+- Plugin not loading: confirm the file exists at `~/.config/opencode/plugins/openviking-memory.ts`
+- Service unavailable: confirm `openviking-server` is running and reachable at the configured endpoint
+- Authentication failed: check `OPENVIKING_API_KEY` or `openviking-config.json`
+- No memories extracted: check that your OpenViking server has working `vlm` and `embedding` configuration
diff --git a/examples/opencode-memory-plugin/openviking-config.example.json b/examples/opencode-memory-plugin/openviking-config.example.json
new file mode 100644
index 000000000..ab541fcf7
--- /dev/null
+++ b/examples/opencode-memory-plugin/openviking-config.example.json
@@ -0,0 +1,10 @@
+{
+ "endpoint": "http://localhost:1933",
+ "apiKey": "your-api-key-here",
+ "enabled": true,
+ "timeoutMs": 30000,
+ "autoCommit": {
+ "enabled": true,
+ "intervalMinutes": 10
+ }
+}
diff --git a/examples/opencode-memory-plugin/openviking-memory.ts b/examples/opencode-memory-plugin/openviking-memory.ts
new file mode 100644
index 000000000..8f88bf704
--- /dev/null
+++ b/examples/opencode-memory-plugin/openviking-memory.ts
@@ -0,0 +1,1751 @@
+/**
+ * OpenViking Memory Plugin for OpenCode
+ *
+ * Exposes OpenViking's semantic memory capabilities as tools for AI agents.
+ * Supports user profiles, preferences, entities, events, cases, and patterns.
+ */
+
+import type { Hooks, PluginInput } from "@opencode-ai/plugin"
+import { tool } from "@opencode-ai/plugin"
+import * as fs from "fs"
+import * as path from "path"
+import { fileURLToPath } from "url"
+
+const z = tool.schema
+const pluginFilePath = fileURLToPath(import.meta.url)
+const pluginFileDir = path.dirname(pluginFilePath)
+
+// ============================================================================
+// Session State Management
+// ============================================================================
+
+interface SessionMapping {
+ ovSessionId: string
+ createdAt: number
+ capturedMessages: Set<string> // Track captured message IDs to avoid duplicates
+ messageRoles: Map<string, "user" | "assistant"> // Track message ID → role mapping
+ pendingMessages: Map<string, string> // Track message ID → content for messages waiting for completion
+ sendingMessages: Set<string> // Track message IDs currently being sent to avoid duplicate writes
+ lastCommitTime?: number
+ commitInFlight?: boolean
+ commitTaskId?: string
+ commitStartedAt?: number
+ pendingCleanup?: boolean
+}
+
+// Persisted format for session mapping (for disk storage)
+interface SessionMappingPersisted {
+ ovSessionId: string
+ createdAt: number
+ capturedMessages: string[] // Set → Array
+ messageRoles: [string, "user" | "assistant"][] // Map → Array of tuples
+ pendingMessages: [string, string][] // Map → Array of tuples
+ lastCommitTime?: number
+ commitInFlight?: boolean
+ commitTaskId?: string
+ commitStartedAt?: number
+ pendingCleanup?: boolean
+}
+
+// Session map file format
+interface SessionMapFile {
+ version: 1
+ sessions: Record<string, SessionMappingPersisted> // opencodeSessionId → mapping
+ lastSaved: number // timestamp
+}
+
+// Map: OpenCode session ID → OpenViking session ID
+const sessionMap = new Map<string, SessionMapping>()
+
+// Buffer for messages that arrive before session mapping is established
+interface BufferedMessage {
+ messageId: string
+ content?: string
+ role?: "user" | "assistant"
+ timestamp: number
+}
+const sessionMessageBuffer = new Map<string, BufferedMessage[]>() // sessionId → messages
+const MAX_BUFFERED_MESSAGES_PER_SESSION = 100
+const BUFFERED_MESSAGE_TTL_MS = 15 * 60 * 1000
+const BUFFER_CLEANUP_INTERVAL_MS = 30 * 1000
+let lastBufferCleanupAt = 0
+
+// ============================================================================
+// Logging
+// ============================================================================
+
+let logFilePath: string | null = null
+let pluginDataDir: string | null = null
+
+function ensurePluginDataDir(): string | null {
+ const pluginDir = pluginFileDir
+ try {
+ fs.mkdirSync(pluginDir, { recursive: true })
+ return pluginDir
+ } catch (error) {
+ console.error("Failed to ensure plugin directory:", error)
+ return null
+ }
+}
+
+function initLogger() {
+ const pluginDir = ensurePluginDataDir()
+ if (!pluginDir) return
+ pluginDataDir = pluginDir
+ logFilePath = path.join(pluginDir, "openviking-memory.log")
+}
+
+function safeStringify(obj: any): any {
+ if (obj === null || obj === undefined) return obj
+ if (typeof obj !== "object") return obj
+
+ // Handle arrays
+ if (Array.isArray(obj)) {
+ return obj.map((item) => safeStringify(item))
+ }
+
+ // Handle objects
+ const result: any = {}
+ for (const key in obj) {
+ if (Object.prototype.hasOwnProperty.call(obj, key)) {
+ const value = obj[key]
+ if (typeof value === "function") {
+ result[key] = "[Function]"
+ } else if (typeof value === "object" && value !== null) {
+ try {
+ result[key] = safeStringify(value)
+ } catch {
+ result[key] = "[Circular or Non-serializable]"
+ }
+ } else {
+ result[key] = value
+ }
+ }
+ }
+ return result
+}
+
+function log(level: "INFO" | "ERROR" | "DEBUG", toolName: string, message: string, data?: any) {
+ if (!logFilePath) return
+
+ const timestamp = new Date().toISOString()
+ const logEntry = {
+ timestamp,
+ level,
+ tool: toolName,
+ message,
+ ...(data && { data: safeStringify(data) }),
+ }
+
+ try {
+ const logLine = JSON.stringify(logEntry) + "\n"
+ fs.appendFileSync(logFilePath, logLine, "utf-8")
+ } catch (error) {
+ console.error("Failed to write to log file:", error)
+ }
+}
+
+// ============================================================================
+// Session Map Persistence
+// ============================================================================
+
+let sessionMapPath: string | null = null
+
+function initSessionMapPath() {
+ const pluginDir = pluginDataDir ?? ensurePluginDataDir()
+ if (!pluginDir) return
+ pluginDataDir = pluginDir
+ sessionMapPath = path.join(pluginDir, "openviking-session-map.json")
+}
+
+function serializeSessionMapping(mapping: SessionMapping): SessionMappingPersisted {
+ return {
+ ovSessionId: mapping.ovSessionId,
+ createdAt: mapping.createdAt,
+ capturedMessages: Array.from(mapping.capturedMessages),
+ messageRoles: Array.from(mapping.messageRoles.entries()),
+ pendingMessages: Array.from(mapping.pendingMessages.entries()),
+ lastCommitTime: mapping.lastCommitTime,
+ commitInFlight: mapping.commitInFlight,
+ commitTaskId: mapping.commitTaskId,
+ commitStartedAt: mapping.commitStartedAt,
+ pendingCleanup: mapping.pendingCleanup,
+ }
+}
+
+function deserializeSessionMapping(persisted: SessionMappingPersisted): SessionMapping {
+ return {
+ ovSessionId: persisted.ovSessionId,
+ createdAt: persisted.createdAt,
+ capturedMessages: new Set(persisted.capturedMessages),
+ messageRoles: new Map(persisted.messageRoles),
+ pendingMessages: new Map(persisted.pendingMessages),
+ sendingMessages: new Set(),
+ lastCommitTime: persisted.lastCommitTime,
+ commitInFlight: persisted.commitInFlight,
+ commitTaskId: persisted.commitTaskId,
+ commitStartedAt: persisted.commitStartedAt,
+ pendingCleanup: persisted.pendingCleanup,
+ }
+}
+
+async function loadSessionMap(): Promise<void> {
+ if (!sessionMapPath) return
+
+ try {
+ if (!fs.existsSync(sessionMapPath)) {
+ log("INFO", "persistence", "No session map file found, starting fresh")
+ return
+ }
+
+ const content = await fs.promises.readFile(sessionMapPath, "utf-8")
+ const data: SessionMapFile = JSON.parse(content)
+
+ if (data.version !== 1) {
+ log("ERROR", "persistence", "Unsupported session map version", { version: data.version })
+ return
+ }
+
+ for (const [opencodeSessionId, persisted] of Object.entries(data.sessions)) {
+ sessionMap.set(opencodeSessionId, deserializeSessionMapping(persisted))
+ }
+
+ log("INFO", "persistence", "Session map loaded", {
+ count: sessionMap.size,
+ last_saved: new Date(data.lastSaved).toISOString()
+ })
+ } catch (error: any) {
+ log("ERROR", "persistence", "Failed to load session map", { error: error.message })
+
+ // Backup corrupted file
+ if (fs.existsSync(sessionMapPath)) {
+ const backupPath = `${sessionMapPath}.corrupted.${Date.now()}`
+ await fs.promises.rename(sessionMapPath, backupPath)
+ log("INFO", "persistence", "Corrupted file backed up", { backup: backupPath })
+ }
+ }
+}
+
+async function saveSessionMap(): Promise<void> {
+ if (!sessionMapPath) return
+
+ try {
+ const sessions: Record<string, SessionMappingPersisted> = {}
+ for (const [opencodeSessionId, mapping] of sessionMap.entries()) {
+ sessions[opencodeSessionId] = serializeSessionMapping(mapping)
+ }
+
+ const data: SessionMapFile = {
+ version: 1,
+ sessions,
+ lastSaved: Date.now()
+ }
+
+ // Atomic write: temp file + rename
+ const tempPath = sessionMapPath + '.tmp'
+ await fs.promises.writeFile(tempPath, JSON.stringify(data, null, 2), "utf-8")
+ await fs.promises.rename(tempPath, sessionMapPath)
+
+ log("DEBUG", "persistence", "Session map saved", { count: sessionMap.size })
+ } catch (error: any) {
+ log("ERROR", "persistence", "Failed to save session map", { error: error.message })
+ }
+}
+
+// Debounced save to reduce disk I/O
+let saveTimer: NodeJS.Timeout | null = null
+
+function debouncedSaveSessionMap(): void {
+ if (saveTimer) clearTimeout(saveTimer)
+ saveTimer = setTimeout(() => {
+ saveSessionMap().catch(error => {
+ log("ERROR", "persistence", "Debounced save failed", { error: error.message })
+ })
+ }, 300)
+}
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+interface OpenVikingConfig {
+ endpoint: string
+ apiKey: string
+ enabled: boolean
+ timeoutMs: number
+ autoCommit?: {
+ enabled: boolean
+ intervalMinutes: number
+ }
+}
+
+// ============================================================================
+// API Response Types
+// ============================================================================
+
+interface OpenVikingResponse<T = unknown> {
+ status: string
+ result?: T
+ error?: string | { code?: string; message?: string; details?: Record<string, unknown> }
+ time?: number
+ usage?: Record<string, number>
+}
+
+interface SearchResult {
+ memories: any[]
+ resources: any[]
+ skills: any[]
+ total: number
+ query_plan?: string
+}
+
+interface CommitResult {
+ session_id: string
+ status: string
+ memories_extracted: number
+ active_count_updated: number
+ archived: boolean
+ task_id?: string
+ message?: string
+ stats?: {
+ total_turns?: number
+ contexts_used?: number
+ skills_used?: number
+ memories_extracted?: number
+ }
+}
+
+interface SessionResult {
+ session_id: string
+}
+
+interface TaskResult {
+ task_id: string
+ task_type: string
+ status: "pending" | "running" | "completed" | "failed"
+ created_at: number
+ updated_at: number
+ resource_id?: string
+ result?: {
+ session_id?: string
+ memories_extracted?: number
+ archived?: boolean
+ }
+ error?: string | null
+}
+
+const DEFAULT_CONFIG: OpenVikingConfig = {
+ endpoint: "http://localhost:1933",
+ apiKey: "",
+ enabled: true,
+ timeoutMs: 30000,
+ autoCommit: {
+ enabled: true,
+ intervalMinutes: 10
+ }
+}
+
+function loadConfig(): OpenVikingConfig {
+ const configPath = path.join(pluginFileDir, "openviking-config.json")
+
+ try {
+ if (fs.existsSync(configPath)) {
+ const fileContent = fs.readFileSync(configPath, "utf-8")
+ const fileConfig = JSON.parse(fileContent)
+ const config = {
+ ...DEFAULT_CONFIG,
+ ...fileConfig,
+ autoCommit: fileConfig.autoCommit
+ ? {
+ ...DEFAULT_CONFIG.autoCommit,
+ ...fileConfig.autoCommit,
+ }
+ : DEFAULT_CONFIG.autoCommit
+ ? { ...DEFAULT_CONFIG.autoCommit }
+ : undefined,
+ }
+ if (config.autoCommit) {
+ config.autoCommit.intervalMinutes = getAutoCommitIntervalMinutes(config)
+ }
+
+ // Environment variable takes precedence over config file
+ if (process.env.OPENVIKING_API_KEY) {
+ config.apiKey = process.env.OPENVIKING_API_KEY
+ }
+
+ return config
+ }
+ } catch (error) {
+ console.warn(`Failed to load OpenViking config from ${configPath}:`, error)
+ }
+
+ // Check environment variable even if config file doesn't exist
+ const config = {
+ ...DEFAULT_CONFIG,
+ autoCommit: DEFAULT_CONFIG.autoCommit
+ ? { ...DEFAULT_CONFIG.autoCommit }
+ : undefined,
+ }
+ if (process.env.OPENVIKING_API_KEY) {
+ config.apiKey = process.env.OPENVIKING_API_KEY
+ }
+ if (config.autoCommit) {
+ config.autoCommit.intervalMinutes = getAutoCommitIntervalMinutes(config)
+ }
+
+ return config
+}
+
+// ============================================================================
+// HTTP Client
+// ============================================================================
+
+interface HttpRequestOptions {
+ method: "GET" | "POST" | "PUT" | "DELETE"
+ endpoint: string
+ body?: any
+ timeoutMs?: number
+ abortSignal?: AbortSignal
+}
+
+async function makeRequest<T = any>(config: OpenVikingConfig, options: HttpRequestOptions): Promise<T> {
+ const url = `${config.endpoint}${options.endpoint}`
+ const headers: Record<string, string> = {
+ "Content-Type": "application/json",
+ }
+
+ if (config.apiKey) {
+ headers["X-API-Key"] = config.apiKey
+ }
+
+ const controller = new AbortController()
+ const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? config.timeoutMs)
+
+ // Chain with tool's abort signal if provided
+ const signal = options.abortSignal
+ ? AbortSignal.any([options.abortSignal, controller.signal])
+ : controller.signal
+
+ try {
+ const response = await fetch(url, {
+ method: options.method,
+ headers,
+ body: options.body ? JSON.stringify(options.body) : undefined,
+ signal,
+ })
+
+ clearTimeout(timeout)
+
+ if (!response.ok) {
+ const errorText = await response.text()
+ let errorMessage: string
+ try {
+ const errorJson = JSON.parse(errorText)
+ // Handle case where error/message might be objects
+ const rawError = errorJson.error || errorJson.message
+ if (typeof rawError === "string") {
+ errorMessage = rawError
+ } else if (rawError && typeof rawError === "object") {
+ errorMessage = JSON.stringify(rawError)
+ } else {
+ errorMessage = errorText
+ }
+ } catch {
+ errorMessage = errorText
+ }
+
+ switch (response.status) {
+ case 401:
+ case 403:
+ throw new Error("Authentication failed. Please check API key configuration.")
+ case 404:
+ throw new Error(`Resource not found: ${options.endpoint}`)
+ case 500:
+ throw new Error(`OpenViking server error: ${errorMessage}`)
+ default:
+ throw new Error(`Request failed (${response.status}): ${errorMessage}`)
+ }
+ }
+
+ return (await response.json()) as T
+ } catch (error: any) {
+ clearTimeout(timeout)
+
+ if (error.name === "AbortError") {
+ throw new Error(`Request timeout after ${options.timeoutMs ?? config.timeoutMs}ms`)
+ }
+
+ if (error.message?.includes("fetch failed") || error.code === "ECONNREFUSED") {
+ throw new Error(
+ `OpenViking service unavailable at ${config.endpoint}. Please check if the service is running (try: openviking-server).`,
+ )
+ }
+
+ throw error
+ }
+}
+
+function getResponseErrorMessage(error: OpenVikingResponse["error"]): string {
+ if (!error) return "Unknown OpenViking error"
+ if (typeof error === "string") return error
+ return error.message || error.code || "Unknown OpenViking error"
+}
+
+function unwrapResponse<T>(response: OpenVikingResponse<T>): T {
+ if (!response || typeof response !== "object") {
+ throw new Error("OpenViking returned an invalid response")
+ }
+ if (response.status && response.status !== "ok") {
+ throw new Error(getResponseErrorMessage(response.error))
+ }
+ return response.result as T
+}
+
+async function checkServiceHealth(config: OpenVikingConfig): Promise<boolean> {
+ try {
+ const response = await fetch(`${config.endpoint}/health`, {
+ method: "GET",
+ signal: AbortSignal.timeout(3000),
+ })
+ return response.ok
+ } catch (error: any) {
+ log("ERROR", "health", "OpenViking health check failed", {
+ endpoint: config.endpoint,
+ error: error.message,
+ })
+ return false
+ }
+}
+
+// ============================================================================
+// Session Lifecycle Helpers
+// ============================================================================
+
+function mergeMessageContent(existing: string | undefined, incoming: string): string {
+ const next = incoming.trim()
+ if (!next) return existing ?? ""
+ if (!existing) return next
+ if (next === existing) return existing
+ if (next.startsWith(existing)) return next
+ if (existing.startsWith(next)) return existing
+ if (next.includes(existing)) return next
+ if (existing.includes(next)) return existing
+ return `${existing}\n${next}`.trim()
+}
+
+function upsertBufferedMessage(
+ sessionId: string,
+ messageId: string,
+ updates: Partial<Pick<BufferedMessage, "role" | "content">>,
+): void {
+ const now = Date.now()
+
+ if (now - lastBufferCleanupAt >= BUFFER_CLEANUP_INTERVAL_MS) {
+ for (const [bufferedSessionId, bufferedMessages] of sessionMessageBuffer.entries()) {
+ const freshMessages = bufferedMessages.filter((message) => now - message.timestamp <= BUFFERED_MESSAGE_TTL_MS)
+ if (freshMessages.length === 0) {
+ sessionMessageBuffer.delete(bufferedSessionId)
+ continue
+ }
+ if (freshMessages.length !== bufferedMessages.length) {
+ sessionMessageBuffer.set(bufferedSessionId, freshMessages)
+ }
+ }
+ lastBufferCleanupAt = now
+ }
+
+ const existingBuffer = sessionMessageBuffer.get(sessionId) ?? []
+ const freshBuffer = existingBuffer.filter((message) => now - message.timestamp <= BUFFERED_MESSAGE_TTL_MS)
+
+ let buffered = freshBuffer.find((message) => message.messageId === messageId)
+ if (!buffered) {
+ while (freshBuffer.length >= MAX_BUFFERED_MESSAGES_PER_SESSION) {
+ freshBuffer.shift()
+ }
+ buffered = { messageId, timestamp: now }
+ freshBuffer.push(buffered)
+ } else {
+ buffered.timestamp = now
+ }
+
+ if (updates.role) {
+ buffered.role = updates.role
+ }
+ if (updates.content) {
+ buffered.content = mergeMessageContent(buffered.content, updates.content)
+ }
+
+ sessionMessageBuffer.set(sessionId, freshBuffer)
+}
+
+function getAutoCommitIntervalMinutes(config: OpenVikingConfig): number {
+ const configured = Number(config.autoCommit?.intervalMinutes ?? DEFAULT_CONFIG.autoCommit?.intervalMinutes ?? 10)
+ if (!Number.isFinite(configured)) {
+ return DEFAULT_CONFIG.autoCommit?.intervalMinutes ?? 10
+ }
+ return Math.max(1, configured)
+}
+
+function resolveEventSessionId(event: any): string | undefined {
+ return event?.properties?.info?.id
+ ?? event?.properties?.sessionID
+ ?? event?.properties?.sessionId
+}
+
+/**
+ * Create or connect to OpenViking session for an OpenCode session
+ */
+async function ensureOpenVikingSession(
+ opencodeSessionId: string,
+ config: OpenVikingConfig,
+): Promise<string | null> {
+ const existingMapping = sessionMap.get(opencodeSessionId)
+ const knownSessionId = existingMapping?.ovSessionId
+
+ if (knownSessionId) {
+ try {
+ const response = await makeRequest<OpenVikingResponse<SessionResult>>(config, {
+ method: "GET",
+ endpoint: `/api/v1/sessions/${knownSessionId}`,
+ timeoutMs: 5000,
+ })
+ const result = unwrapResponse(response)
+ if (result) {
+ log("INFO", "session", "Reconnected to persisted OpenViking session", {
+ opencode_session: opencodeSessionId,
+ openviking_session: knownSessionId,
+ })
+ return knownSessionId
+ }
+ } catch (error: any) {
+ log("INFO", "session", "Persisted OpenViking session unavailable, creating a new one", {
+ opencode_session: opencodeSessionId,
+ openviking_session: knownSessionId,
+ error: error.message,
+ })
+ }
+ }
+
+ try {
+ const createResponse = await makeRequest<OpenVikingResponse<SessionResult>>(config, {
+ method: "POST",
+ endpoint: "/api/v1/sessions",
+ body: {},
+ timeoutMs: 5000,
+ })
+
+ const sessionId = unwrapResponse(createResponse)?.session_id
+ if (!sessionId) {
+ throw new Error("OpenViking did not return a session_id")
+ }
+
+ log("INFO", "session", "Created new OpenViking session", {
+ opencode_session: opencodeSessionId,
+ openviking_session: sessionId,
+ })
+ return sessionId
+ } catch (error: any) {
+ log("ERROR", "session", "Failed to create OpenViking session", {
+ opencode_session: opencodeSessionId,
+ error: error.message,
+ })
+ return null
+ }
+}
+
+async function sleep(ms: number, abortSignal?: AbortSignal): Promise<void> {
+ await new Promise<void>((resolve, reject) => {
+ const timer = setTimeout(() => {
+ abortSignal?.removeEventListener("abort", onAbort)
+ resolve()
+ }, ms)
+
+ function onAbort() {
+ clearTimeout(timer)
+ reject(new Error("Operation aborted"))
+ }
+
+ abortSignal?.addEventListener("abort", onAbort, { once: true })
+ })
+}
+
+async function findRunningCommitTaskId(
+ ovSessionId: string,
+ config: OpenVikingConfig,
+): Promise<string | undefined> {
+ try {
+ const response = await makeRequest<OpenVikingResponse<TaskResult[]>>(config, {
+ method: "GET",
+ endpoint: `/api/v1/tasks?task_type=session_commit&resource_id=${encodeURIComponent(ovSessionId)}&limit=10`,
+ timeoutMs: 5000,
+ })
+ const tasks = unwrapResponse(response) ?? []
+ const runningTask = tasks.find((task) => task.status === "pending" || task.status === "running")
+ return runningTask?.task_id
+ } catch (error: any) {
+ log("ERROR", "session", "Failed to query running commit tasks", {
+ openviking_session: ovSessionId,
+ error: error.message,
+ })
+ return undefined
+ }
+}
+
+function clearCommitState(mapping: SessionMapping): void {
+ mapping.commitInFlight = false
+ mapping.commitTaskId = undefined
+ mapping.commitStartedAt = undefined
+}
+
+async function flushPendingMessages(
+ opencodeSessionId: string,
+ mapping: SessionMapping,
+ config: OpenVikingConfig,
+): Promise<void> {
+ if (mapping.commitInFlight) {
+ return
+ }
+
+ for (const messageId of Array.from(mapping.pendingMessages.keys())) {
+ if (mapping.capturedMessages.has(messageId) || mapping.sendingMessages.has(messageId)) {
+ continue
+ }
+ const role = mapping.messageRoles.get(messageId)
+ const content = mapping.pendingMessages.get(messageId)
+ if (!role || !content || !content.trim()) {
+ continue
+ }
+
+ mapping.sendingMessages.add(messageId)
+ try {
+ log("DEBUG", "message", "Committing pending message content", {
+ session_id: opencodeSessionId,
+ message_id: messageId,
+ role,
+ content_length: content.length,
+ })
+
+ const success = await addMessageToSession(
+ mapping.ovSessionId,
+ role,
+ content,
+ config
+ )
+
+ if (success) {
+ const latestContent = mapping.pendingMessages.get(messageId)
+ if (latestContent && latestContent !== content) {
+ log("DEBUG", "message", "Message changed during send; keeping latest content pending", {
+ session_id: opencodeSessionId,
+ message_id: messageId,
+ role,
+ previous_length: content.length,
+ latest_length: latestContent.length,
+ })
+ } else {
+ mapping.capturedMessages.add(messageId)
+ mapping.pendingMessages.delete(messageId)
+ debouncedSaveSessionMap()
+ log("INFO", "message", `${role} message captured successfully`, {
+ session_id: opencodeSessionId,
+ message_id: messageId,
+ role,
+ })
+ }
+ }
+ } finally {
+ mapping.sendingMessages.delete(messageId)
+ }
+ }
+}
+
+async function startBackgroundCommit(
+ mapping: SessionMapping,
+ opencodeSessionId: string,
+ config: OpenVikingConfig,
+): Promise<string | null> {
+ if (mapping.commitInFlight && mapping.commitTaskId) {
+ return mapping.commitTaskId
+ }
+
+ try {
+ const response = await makeRequest<OpenVikingResponse<CommitResult>>(config, {
+ method: "POST",
+ endpoint: `/api/v1/sessions/${mapping.ovSessionId}/commit?wait=false`,
+ timeoutMs: 5000,
+ })
+ const data = unwrapResponse(response)
+ const taskId = data?.task_id
+ if (!taskId) {
+ throw new Error("OpenViking did not return a background task id")
+ }
+
+ mapping.commitInFlight = true
+ mapping.commitTaskId = taskId
+ mapping.commitStartedAt = Date.now()
+ debouncedSaveSessionMap()
+
+ log("INFO", "session", "OpenViking background commit accepted", {
+ openviking_session: mapping.ovSessionId,
+ opencode_session: opencodeSessionId,
+ task_id: taskId,
+ })
+ return taskId
+ } catch (error: any) {
+ if (error.message?.includes("already has a commit in progress")) {
+ const taskId = await findRunningCommitTaskId(mapping.ovSessionId, config)
+ if (taskId) {
+ mapping.commitInFlight = true
+ mapping.commitTaskId = taskId
+ mapping.commitStartedAt = mapping.commitStartedAt ?? Date.now()
+ debouncedSaveSessionMap()
+ log("INFO", "session", "Recovered existing background commit task", {
+ openviking_session: mapping.ovSessionId,
+ opencode_session: opencodeSessionId,
+ task_id: taskId,
+ })
+ return taskId
+ }
+ }
+
+ log("ERROR", "session", "Failed to start OpenViking background commit", {
+ openviking_session: mapping.ovSessionId,
+ opencode_session: opencodeSessionId,
+ error: error.message,
+ })
+ return null
+ }
+}
+
+async function pollCommitTaskOnce(
+ mapping: SessionMapping,
+ opencodeSessionId: string,
+ config: OpenVikingConfig,
+): Promise<TaskResult["status"] | "unknown"> {
+ if (!mapping.commitInFlight) {
+ return "unknown"
+ }
+
+ if (!mapping.commitTaskId) {
+ const recoveredTaskId = await findRunningCommitTaskId(mapping.ovSessionId, config)
+ if (!recoveredTaskId) {
+ log("ERROR", "session", "Commit marked in-flight without task id; clearing state", {
+ openviking_session: mapping.ovSessionId,
+ opencode_session: opencodeSessionId,
+ })
+ clearCommitState(mapping)
+ debouncedSaveSessionMap()
+ return "unknown"
+ }
+ mapping.commitTaskId = recoveredTaskId
+ }
+
+ try {
+ const response = await makeRequest<OpenVikingResponse<TaskResult>>(config, {
+ method: "GET",
+ endpoint: `/api/v1/tasks/${mapping.commitTaskId}`,
+ timeoutMs: 5000,
+ })
+ const task = unwrapResponse(response)
+
+ if (task.status === "pending" || task.status === "running") {
+ return task.status
+ }
+
+ if (task.status === "completed") {
+ const memoriesExtracted = task.result?.memories_extracted ?? 0
+ const archived = task.result?.archived ?? false
+
+ log("INFO", "session", "OpenViking background commit completed", {
+ openviking_session: mapping.ovSessionId,
+ opencode_session: opencodeSessionId,
+ task_id: task.task_id,
+ memories_extracted: memoriesExtracted,
+ archived,
+ })
+
+ mapping.lastCommitTime = Date.now()
+ mapping.capturedMessages.clear()
+ clearCommitState(mapping)
+ debouncedSaveSessionMap()
+
+ await flushPendingMessages(opencodeSessionId, mapping, config)
+
+ if (mapping.pendingCleanup) {
+ sessionMap.delete(opencodeSessionId)
+ sessionMessageBuffer.delete(opencodeSessionId)
+ await saveSessionMap()
+ log("INFO", "session", "Cleaned up session mapping after commit completion", {
+ openviking_session: mapping.ovSessionId,
+ opencode_session: opencodeSessionId,
+ })
+ }
+
+ return task.status
+ }
+
+ log("ERROR", "session", "OpenViking background commit failed", {
+ openviking_session: mapping.ovSessionId,
+ opencode_session: opencodeSessionId,
+ task_id: task.task_id,
+ error: task.error,
+ })
+
+ clearCommitState(mapping)
+ debouncedSaveSessionMap()
+
+ if (mapping.pendingCleanup) {
+ sessionMap.delete(opencodeSessionId)
+ sessionMessageBuffer.delete(opencodeSessionId)
+ await saveSessionMap()
+ log("INFO", "session", "Cleaned up session mapping after failed commit", {
+ openviking_session: mapping.ovSessionId,
+ opencode_session: opencodeSessionId,
+ })
+ }
+
+ return task.status
+ } catch (error: any) {
+ log("ERROR", "session", "Failed to poll OpenViking background commit", {
+ openviking_session: mapping.ovSessionId,
+ opencode_session: opencodeSessionId,
+ task_id: mapping.commitTaskId,
+ error: error.message,
+ })
+ return "unknown"
+ }
+}
+
+async function waitForCommitCompletion(
+ mapping: SessionMapping,
+ opencodeSessionId: string,
+ config: OpenVikingConfig,
+ abortSignal?: AbortSignal,
+ timeoutMs = 180000,
+): Promise<TaskResult | null> {
+ const startedAt = Date.now()
+
+ while (Date.now() - startedAt < timeoutMs) {
+ if (abortSignal?.aborted) {
+ throw new Error("Operation aborted")
+ }
+
+ if (!mapping.commitInFlight || !mapping.commitTaskId) {
+ return null
+ }
+
+ const response = await makeRequest<OpenVikingResponse<TaskResult>>(config, {
+ method: "GET",
+ endpoint: `/api/v1/tasks/${mapping.commitTaskId}`,
+ timeoutMs: 5000,
+ abortSignal,
+ })
+ const task = unwrapResponse(response)
+
+ if (task.status === "completed") {
+ const memoriesExtracted = task.result?.memories_extracted ?? 0
+ const archived = task.result?.archived ?? false
+
+ mapping.lastCommitTime = Date.now()
+ mapping.capturedMessages.clear()
+ clearCommitState(mapping)
+ debouncedSaveSessionMap()
+
+ await flushPendingMessages(opencodeSessionId, mapping, config)
+
+ log("INFO", "memcommit", "Background commit completed while waiting", {
+ openviking_session: mapping.ovSessionId,
+ opencode_session: opencodeSessionId,
+ task_id: task.task_id,
+ memories_extracted: memoriesExtracted,
+ archived,
+ })
+ return task
+ }
+
+ if (task.status === "failed") {
+ clearCommitState(mapping)
+ debouncedSaveSessionMap()
+ throw new Error(task.error || "Background commit failed")
+ }
+
+ await sleep(2000, abortSignal)
+ }
+
+ return null
+}
+
+// ============================================================================
+// Auto-Commit Scheduler
+// ============================================================================
+
+let autoCommitTimer: NodeJS.Timeout | null = null
+
+function startAutoCommit(config: OpenVikingConfig) {
+ if (!config.autoCommit?.enabled) {
+ log("INFO", "auto-commit", "Auto-commit disabled in config")
+ return
+ }
+
+ const checkIntervalMs = 60 * 1000 // Check every minute
+
+ autoCommitTimer = setInterval(async () => {
+ await checkAndCommitSessions(config)
+ }, checkIntervalMs)
+
+ log("INFO", "auto-commit", "Auto-commit scheduler started", {
+ check_interval_seconds: 60,
+ commit_interval_minutes: getAutoCommitIntervalMinutes(config)
+ })
+}
+
+function stopAutoCommit() {
+ if (autoCommitTimer) {
+ clearInterval(autoCommitTimer)
+ autoCommitTimer = null
+ log("INFO", "auto-commit", "Auto-commit scheduler stopped")
+ }
+}
+
+async function checkAndCommitSessions(config: OpenVikingConfig): Promise<void> {
+ const intervalMs = getAutoCommitIntervalMinutes(config) * 60 * 1000
+ const now = Date.now()
+
+ for (const [opencodeSessionId, mapping] of sessionMap.entries()) {
+ if (mapping.commitInFlight) {
+ await pollCommitTaskOnce(mapping, opencodeSessionId, config)
+ continue
+ }
+
+ if (mapping.pendingMessages.size > 0) {
+ await flushPendingMessages(opencodeSessionId, mapping, config)
+ }
+
+ const timeSinceLastCommit = now - (mapping.lastCommitTime ?? mapping.createdAt)
+ const hasNewMessages = mapping.capturedMessages.size > 0
+
+ if (timeSinceLastCommit >= intervalMs && hasNewMessages) {
+ log("INFO", "auto-commit", "Triggering auto-commit", {
+ opencode_session: opencodeSessionId,
+ openviking_session: mapping.ovSessionId,
+ time_since_last_commit_minutes: Math.floor(timeSinceLastCommit / 60000),
+ captured_messages_count: mapping.capturedMessages.size
+ })
+
+ await startBackgroundCommit(mapping, opencodeSessionId, config)
+ }
+ }
+}
+
+/**
+ * Add message to OpenViking session
+ */
+async function addMessageToSession(
+ ovSessionId: string,
+ role: "user" | "assistant",
+ content: string,
+ config: OpenVikingConfig,
+): Promise<boolean> {
+ try {
+ const response = await makeRequest<OpenVikingResponse<void>>(config, {
+ method: "POST",
+ endpoint: `/api/v1/sessions/${ovSessionId}/messages`,
+ body: { role, content },
+ timeoutMs: 5000,
+ })
+ unwrapResponse(response)
+
+ log("INFO", "message", "Message added to OpenViking session", {
+ openviking_session: ovSessionId,
+ role,
+ content_length: content.length,
+ })
+ return true
+ } catch (error: any) {
+ log("ERROR", "message", "Failed to add message to OpenViking session", {
+ openviking_session: ovSessionId,
+ role,
+ error: error.message,
+ })
+ return false
+ }
+}
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+function formatSearchResults(
+ result: SearchResult,
+ toolName: string,
+ query: string,
+ extra?: Record<string, unknown>
+): string {
+ const { memories = [], resources = [], skills = [] } = result
+ const allResults = [...memories, ...resources, ...skills]
+ if (allResults.length === 0) {
+ log("INFO", toolName, "No results found", { query })
+ return "No results found matching the query."
+ }
+ log("INFO", toolName, "Search completed", { count: allResults.length })
+ return JSON.stringify(
+ { total: result.total ?? allResults.length, memories, resources, skills, ...extra },
+ null, 2
+ )
+}
+
+function resolveSearchMode(
+ requestedMode: "auto" | "fast" | "deep" | undefined,
+ query: string,
+ sessionId?: string
+): "fast" | "deep" {
+ if (requestedMode === "fast" || requestedMode === "deep") {
+ return requestedMode
+ }
+
+ if (sessionId) {
+ return "deep"
+ }
+
+ const normalized = query.trim()
+ const wordCount = normalized ? normalized.split(/\s+/).length : 0
+ if (normalized.includes("?") || normalized.length >= 80 || wordCount >= 8) {
+ return "deep"
+ }
+
+ return "fast"
+}
+
+function validateVikingUri(uri: string, toolName: string): string | null {
+ if (!uri.startsWith("viking://")) {
+ const error = `Invalid URI format. Must start with "viking://". Example: viking://user/memories/`
+ log("ERROR", toolName, "Invalid URI format", { uri })
+ return `Error: ${error}`
+ }
+ return null
+}
+
+// ============================================================================
+// Plugin Export
+// ============================================================================
+
+export const OpenVikingMemoryPlugin = async (input: PluginInput): Promise<Hooks> => {
+ const config = loadConfig()
+ initLogger()
+ initSessionMapPath()
+
+ if (!config.enabled) {
+ console.log("OpenViking Memory Plugin is disabled in configuration")
+ return {}
+ }
+
+ log("INFO", "plugin", "OpenViking Memory Plugin initialized", { endpoint: config.endpoint })
+
+ // Load session map from disk
+ await loadSessionMap()
+
+ const healthy = await checkServiceHealth(config)
+ log("INFO", "health", healthy ? "OpenViking health check passed" : "OpenViking health check failed", {
+ endpoint: config.endpoint,
+ })
+
+ // Start auto-commit scheduler
+ startAutoCommit(config)
+
+ return {
+ event: async ({ event }) => {
+ if (event && event.type && event.type === "session.diff") {
+ return;
+ }
+
+ // Handle session lifecycle events
+ if (event.type === "session.created") {
+ const sessionId = resolveEventSessionId(event)
+ if (!sessionId) {
+ log("ERROR", "event", "session.created event missing sessionId", {
+ event: safeStringify(event)
+ })
+ return
+ }
+
+ log("INFO", "event", "OpenCode session created", {
+ session_id: sessionId,
+ session_info: safeStringify(event.properties?.info)
+ })
+
+ // Create or connect to OpenViking session (non-blocking)
+ const ovSessionId = await ensureOpenVikingSession(sessionId, config)
+ if (ovSessionId) {
+ sessionMap.set(sessionId, {
+ ovSessionId,
+ createdAt: Date.now(),
+ capturedMessages: new Set(),
+ messageRoles: new Map(),
+ pendingMessages: new Map(),
+ sendingMessages: new Set(),
+ lastCommitTime: undefined,
+ commitInFlight: false,
+ })
+
+ // Process buffered messages that arrived before session mapping
+ const bufferedMessages = sessionMessageBuffer.get(sessionId)
+ if (bufferedMessages && bufferedMessages.length > 0) {
+ log("INFO", "event", "Processing buffered messages", {
+ session_id: sessionId,
+ count: bufferedMessages.length
+ })
+
+ const mapping = sessionMap.get(sessionId)!
+ for (const buffered of bufferedMessages) {
+ // Store role if available
+ if (buffered.role) {
+ mapping.messageRoles.set(buffered.messageId, buffered.role)
+ }
+ // Store content as pending if available
+ if (buffered.content) {
+ mapping.pendingMessages.set(
+ buffered.messageId,
+ mergeMessageContent(mapping.pendingMessages.get(buffered.messageId), buffered.content)
+ )
+ }
+
+ }
+
+ await flushPendingMessages(sessionId, mapping, config)
+
+ // Clear buffer
+ sessionMessageBuffer.delete(sessionId)
+ }
+
+ debouncedSaveSessionMap()
+ log("INFO", "event", "Session mapping established", {
+ opencode_session: sessionId,
+ openviking_session: ovSessionId,
+ session_info: safeStringify(event.properties?.info)
+ })
+ } else {
+ log("ERROR", "event", "Failed to establish session mapping", {
+ session_id: sessionId,
+ session_info: safeStringify(event.properties?.info)
+ })
+ }
+ } else if (event.type === "session.deleted") {
+ const sessionId = resolveEventSessionId(event)
+ if (!sessionId) {
+ log("ERROR", "event", "session.deleted event missing sessionId", {
+ event: safeStringify(event)
+ })
+ return
+ }
+
+ log("INFO", "event", "OpenCode session deleted", {
+ session_id: sessionId,
+ session_info: safeStringify(event.properties?.info)
+ })
+
+ // Commit OpenViking session if mapped
+ const mapping = sessionMap.get(sessionId)
+ if (mapping) {
+ await flushPendingMessages(sessionId, mapping, config)
+
+ if (mapping.capturedMessages.size > 0 || mapping.commitInFlight) {
+ mapping.pendingCleanup = true
+ if (!mapping.commitInFlight) {
+ await startBackgroundCommit(mapping, sessionId, config)
+ }
+ } else {
+ sessionMap.delete(sessionId)
+ sessionMessageBuffer.delete(sessionId) // Clean up buffer
+ await saveSessionMap()
+ log("INFO", "event", "Session mapping removed", {
+ opencode_session: sessionId,
+ openviking_session: mapping.ovSessionId,
+ session_info: safeStringify(event.properties?.info)
+ })
+ }
+ } else {
+ log("INFO", "event", "No session mapping found for deleted session", {
+ session_id: sessionId,
+ session_info: safeStringify(event.properties?.info)
+ })
+ }
+ } else if (event.type === "session.error") {
+ const sessionId = resolveEventSessionId(event)
+ if (!sessionId) {
+ log("ERROR", "event", "session.error event missing sessionId", {
+ event: safeStringify(event)
+ })
+ return
+ }
+
+ log("ERROR", "event", "OpenCode session error", {
+ session_id: sessionId,
+ error: safeStringify(event.error),
+ session_info: safeStringify(event.properties?.info)
+ })
+
+ // Optionally commit session to preserve work
+ const mapping = sessionMap.get(sessionId)
+ if (mapping) {
+ log("INFO", "event", "Attempting to commit session after error", {
+ opencode_session: sessionId,
+ openviking_session: mapping.ovSessionId,
+ session_info: safeStringify(event.properties?.info)
+ })
+ await flushPendingMessages(sessionId, mapping, config)
+
+ if (mapping.capturedMessages.size > 0 || mapping.commitInFlight) {
+ mapping.pendingCleanup = true
+ if (!mapping.commitInFlight) {
+ await startBackgroundCommit(mapping, sessionId, config)
+ }
+ } else {
+ sessionMap.delete(sessionId)
+ sessionMessageBuffer.delete(sessionId) // Clean up buffer
+ await saveSessionMap()
+ }
+ }
+ } else if (event.type === "message.updated") {
+ // Handle message capture for automatic session recording
+ const message = event.properties?.info
+ if (!message) {
+ log("DEBUG", "event", "message.updated event missing info", {
+ event: safeStringify(event)
+ })
+ return
+ }
+
+ const sessionId = message.sessionID
+ const messageId = message.id
+ const role = message.role
+ const finish = message.finish
+
+ // Check if we have a session mapping
+ const mapping = sessionMap.get(sessionId)
+ if (!mapping) {
+ // Buffer this message for later processing
+ upsertBufferedMessage(sessionId, messageId, role ? { role } : {})
+ log("DEBUG", "message", "Message buffered (no session mapping yet)", {
+ session_id: sessionId,
+ message_id: messageId,
+ role: role
+ })
+ return
+ }
+
+ if (role === "user") {
+ if (!mapping.messageRoles.has(messageId)) {
+ mapping.messageRoles.set(messageId, role)
+ log("DEBUG", "message", `${role} message role stored`, {
+ session_id: sessionId,
+ message_id: messageId,
+ role: role,
+ })
+ }
+ } else if (role === "assistant" && finish === "stop") {
+ mapping.messageRoles.set(messageId, role)
+
+ log("DEBUG", "message", `${role} message completed and role stored`, {
+ session_id: sessionId,
+ message_id: messageId,
+ role: role,
+ finish: finish,
+ })
+ }
+
+ await flushPendingMessages(sessionId, mapping, config)
+
+ // For assistant messages: log when fully completed (with tokens/cost)
+ if (role === "assistant" && message.time?.completed) {
+ log("DEBUG", "message", "Assistant message fully completed", {
+ session_id: sessionId,
+ message_id: messageId,
+ tokens: message.tokens,
+ cost: message.cost,
+ })
+ }
+ } else if (event.type === "message.part.updated") {
+ // Handle message part updates to capture content
+ const part = event.properties?.part
+ if (!part) {
+ return
+ }
+
+ const sessionId = part.sessionID
+ const messageId = part.messageID
+ const partType = part.type
+
+ // Check if we have a session mapping
+ const mapping = sessionMap.get(sessionId)
+ if (!mapping) {
+ // Buffer this message content for later processing
+ if (partType === "text" && part.text && part.text.trim().length > 0) {
+ upsertBufferedMessage(sessionId, messageId, { content: part.text })
+ log("DEBUG", "message", "Message content buffered (no session mapping yet)", {
+ session_id: sessionId,
+ message_id: messageId,
+ content_length: part.text.length
+ })
+ }
+ return
+ }
+
+ // Only capture text parts
+ if (partType === "text" && part.text) {
+ // Check if message already captured
+ if (mapping.capturedMessages.has(messageId)) {
+ return
+ }
+
+ const content = part.text
+ if (content && content.trim().length > 0) {
+ mapping.pendingMessages.set(
+ messageId,
+ mergeMessageContent(mapping.pendingMessages.get(messageId), content)
+ )
+ log("DEBUG", "message", "Message content stored as pending", {
+ session_id: sessionId,
+ message_id: messageId,
+ content_length: content.length,
+ waiting_for_role: !mapping.messageRoles.has(messageId),
+ commit_in_flight: mapping.commitInFlight === true,
+ })
+ }
+ }
+ }
+ },
+
+ tool: {
+ memread: tool({
+ description:
+ "Retrieve the content of a specific memory, resource, or skill at a given viking:// URI.\n\nProgressive loading levels:\n- abstract: brief summary\n- overview: structured directory overview\n- read: full content\n- auto: choose overview for directories and read for files\n\nUse when:\n- You have a URI from memsearch or membrowse\n- You need to inspect a memory, resource, or skill in more detail\n\nRequires: Complete viking:// URI (e.g., viking://user/memories/profile.md)",
+ args: {
+ uri: z
+ .string()
+ .describe(
+ "Complete viking:// URI from search results or list output (e.g., viking://user/memories/profile.md, viking://agent/memories/context.md)",
+ ),
+ level: z
+ .enum(["auto", "abstract", "overview", "read"])
+ .optional()
+ .describe("'auto' (directory->overview, file->read), 'abstract' (brief summary), 'overview' (directory summary), 'read' (full content)"),
+ },
+ async execute(args, context) {
+ log("INFO", "memread", "Reading memory", { uri: args.uri, level: args.level })
+
+ // Validate URI format
+ const validationError = validateVikingUri(args.uri, "memread")
+ if (validationError) return validationError
+
+ try {
+ let level = args.level ?? "auto"
+ if (level === "auto") {
+ try {
+ const statResponse = await makeRequest<OpenVikingResponse<{ isDir?: boolean }>>(config, {
+ method: "GET",
+ endpoint: `/api/v1/fs/stat?uri=${encodeURIComponent(args.uri)}`,
+ abortSignal: context.abort,
+ })
+ const statResult = unwrapResponse(statResponse)
+ level = statResult?.isDir ? "overview" : "read"
+ } catch {
+ level = "read"
+ }
+ }
+
+ const response = await makeRequest<OpenVikingResponse<string | Record<string, unknown>>>(config, {
+ method: "GET",
+ endpoint: `/api/v1/content/${level}?uri=${encodeURIComponent(args.uri)}`,
+ abortSignal: context.abort,
+ })
+
+ const content = unwrapResponse(response)
+ if (!content) {
+ log("INFO", "memread", "No content found", { uri: args.uri })
+ return `No content found at ${args.uri}`
+ }
+
+ log("INFO", "memread", "Read completed", { uri: args.uri, level })
+ return typeof content === "string" ? content : JSON.stringify(content, null, 2)
+ } catch (error: any) {
+ log("ERROR", "memread", "Read failed", { error: error.message, uri: args.uri })
+ return `Error: ${error.message}`
+ }
+ },
+ }),
+
+ membrowse: tool({
+ description:
+ "Browse the OpenViking filesystem structure for a specific URI.\n\nViews:\n- list: list immediate children, or recurse when `recursive=true`\n- tree: return a directory tree view\n- stat: return metadata for a single file or directory\n\nUse when:\n- You need to discover available URIs before reading\n- You want to inspect directory structure under memories/resources/skills\n- You need file metadata before deciding how to read it\n\nRequires: Complete viking:// URI",
+ args: {
+ uri: z
+ .string()
+ .describe(
+ "Complete viking:// URI to inspect (e.g., viking://user/memories/, viking://agent/memories/, viking://resources/zh/)",
+ ),
+ view: z
+ .enum(["list", "tree", "stat"])
+ .optional()
+ .describe("'list' for directory listing, 'tree' for recursive tree view, 'stat' for metadata on a single URI"),
+ recursive: z.boolean().optional().describe("Only used with view='list'. Recursively list descendants."),
+ simple: z.boolean().optional().describe("Only used with view='list'. Return simpler URI-oriented output."),
+ },
+ async execute(args, context) {
+ log("INFO", "membrowse", "Browsing URI", { args })
+
+ // Validate URI format
+ const validationError = validateVikingUri(args.uri, "membrowse")
+ if (validationError) return validationError
+
+ try {
+ const view = args.view ?? "list"
+ const encodedUri = encodeURIComponent(args.uri)
+
+ if (view === "stat") {
+ const response = await makeRequest<OpenVikingResponse<Record<string, unknown>>>(config, {
+ method: "GET",
+ endpoint: `/api/v1/fs/stat?uri=${encodedUri}`,
+ abortSignal: context.abort,
+ })
+ const result = unwrapResponse(response)
+ return JSON.stringify({ view, item: result }, null, 2)
+ }
+
+ const endpoint = view === "tree"
+ ? `/api/v1/fs/tree?uri=${encodedUri}`
+ : `/api/v1/fs/ls?uri=${encodedUri}&recursive=${args.recursive ? "true" : "false"}&simple=${args.simple ? "true" : "false"}`
+ const response = await makeRequest<OpenVikingResponse<any[]>>(config, {
+ method: "GET",
+ endpoint,
+ abortSignal: context.abort,
+ })
+
+ const result = unwrapResponse(response)
+ const items = Array.isArray(result) ? result : []
+ if (items.length === 0) {
+ return `No items found at ${args.uri}`
+ }
+
+ return JSON.stringify({ view, count: items.length, items }, null, 2)
+ } catch (error: any) {
+ log("ERROR", "membrowse", "Browse failed", { error: error.message, uri: args.uri })
+ return `Error: ${error.message}`
+ }
+ },
+ }),
+
+ memcommit: tool({
+ description:
+ "Commit the current OpenCode session to OpenViking and extract persistent memories from the accumulated conversation.\n\nBy default this tool commits the OpenViking session mapped to the current OpenCode session. Use `session_id` only when you need to target a specific OpenViking session manually.\n\nUse when:\n- You want a mid-session memory extraction without ending the chat\n- You want recently discussed preferences, entities, or cases persisted immediately\n\nAutomatically extracts and stores:\n- User profile, preferences, entities, events → viking://user/memories/\n- Agent cases and patterns → viking://agent/memories/\n\nReturns background commit progress or completion details, including task_id, memories_extracted, and archived.",
+ args: {
+ session_id: z
+ .string()
+ .optional()
+ .describe("Optional explicit OpenViking session ID. Omit to commit the current OpenCode session's mapped OpenViking session."),
+ },
+ async execute(args, context) {
+ let sessionId = args.session_id
+ if (!sessionId && context.session?.id) {
+ const mapping = sessionMap.get(context.session.id)
+ if (mapping) {
+ sessionId = mapping.ovSessionId
+ }
+ }
+
+ log("INFO", "memcommit", "Committing session", {
+ requested_session_id: args.session_id,
+ resolved_session_id: sessionId,
+ opencode_session_id: context.session?.id,
+ })
+
+ if (!sessionId) {
+ return "Error: No OpenViking session is associated with the current OpenCode session. Start or resume a normal OpenCode session first, or pass an explicit session_id."
+ }
+
+ try {
+ const mapping = context.session?.id ? sessionMap.get(context.session.id) : undefined
+ const resolvedMapping = mapping?.ovSessionId === sessionId ? mapping : undefined
+
+ if (resolvedMapping) {
+ await flushPendingMessages(
+ context.session?.id ?? sessionId,
+ resolvedMapping,
+ config,
+ )
+ }
+
+ if (resolvedMapping?.commitInFlight) {
+ const task = await waitForCommitCompletion(
+ resolvedMapping,
+ context.session?.id ?? sessionId,
+ config,
+ context.abort,
+ )
+ if (task?.status === "completed") {
+ return JSON.stringify(
+ {
+ message: `Memory extraction complete: ${task.result?.memories_extracted ?? 0} memories extracted`,
+ session_id: task.result?.session_id ?? sessionId,
+ status: task.status,
+ memories_extracted: task.result?.memories_extracted ?? 0,
+ archived: task.result?.archived ?? false,
+ task_id: task.task_id,
+ },
+ null,
+ 2,
+ )
+ }
+ }
+
+ const tempMapping: SessionMapping = resolvedMapping ?? {
+ ovSessionId: sessionId,
+ createdAt: Date.now(),
+ capturedMessages: new Set(),
+ messageRoles: new Map(),
+ pendingMessages: new Map(),
+ sendingMessages: new Set(),
+ }
+
+ const taskId = await startBackgroundCommit(
+ tempMapping,
+ context.session?.id ?? sessionId,
+ config,
+ )
+ if (!taskId) {
+ throw new Error("Failed to start background commit")
+ }
+
+ const task = await waitForCommitCompletion(
+ tempMapping,
+ context.session?.id ?? sessionId,
+ config,
+ context.abort,
+ )
+
+ if (!task) {
+ return JSON.stringify(
+ {
+ message: "Commit is still processing in the background",
+ session_id: sessionId,
+ status: "accepted",
+ task_id: taskId,
+ },
+ null,
+ 2,
+ )
+ }
+
+ return JSON.stringify(
+ {
+ message: `Memory extraction complete: ${task.result?.memories_extracted ?? 0} memories extracted`,
+ session_id: task.result?.session_id ?? sessionId,
+ status: task.status,
+ memories_extracted: task.result?.memories_extracted ?? 0,
+ archived: task.result?.archived ?? false,
+ task_id: task.task_id,
+ },
+ null,
+ 2,
+ )
+ } catch (error: any) {
+ log("ERROR", "memcommit", "Commit failed", {
+ error: error.message,
+ session_id: sessionId,
+ })
+ return `Error: ${error.message}`
+ }
+ },
+ }),
+
+ memsearch: tool(
+ {
+ description:
+ "Search OpenViking memories, resources, and skills through a unified interface.\n\nModes:\n- auto: choose between fast similarity search and deep context-aware search\n- fast: use simple semantic similarity search\n- deep: use intent analysis and optional session context\n\nReturns memories, resources, and skills with relevance scores and match reasons.\n\nUse when:\n- You want to find relevant memories or resources by meaning\n- You need a single search tool instead of choosing between low-level APIs\n- You want deeper retrieval for complex or ambiguous questions",
+ args: {
+ query: z.string().describe("Search query - can be natural language, a complex question, or a task description"),
+ target_uri: z
+ .string()
+ .optional()
+ .describe(
+ "Limit search to a specific URI prefix (e.g., viking://resources/, viking://user/memories/). Omit to search all contexts.",
+ ),
+ mode: z
+ .enum(["auto", "fast", "deep"])
+ .optional()
+ .describe("Search mode. 'auto' chooses based on query complexity and session context, 'fast' forces /find, 'deep' forces /search"),
+ session_id: z
+ .string()
+ .optional()
+ .describe(
+ "Optional OpenViking session ID for context-aware search. If omitted in auto/deep mode, the current OpenCode session mapping will be used when available.",
+ ),
+ limit: z.number().optional().describe("Max results (default: 10)"),
+ score_threshold: z.number().optional().describe("Optional minimum score threshold"),
+ },
+ async execute(args, context) {
+ log("INFO", "memsearch", "Executing unified search", { args })
+
+ // Auto-inject session_id if not provided
+ let sessionId = args.session_id
+ if (!sessionId && context.session?.id) {
+ const mapping = sessionMap.get(context.session.id)
+ if (mapping) {
+ sessionId = mapping.ovSessionId
+ log("INFO", "memsearch", "Auto-injected session context", {
+ opencode_session: context.session.id,
+ openviking_session: sessionId,
+ })
+ }
+ }
+
+ const mode = resolveSearchMode(args.mode, args.query, sessionId)
+ const requestBody: {
+ query: string
+ limit: number
+ target_uri?: string
+ session_id?: string
+ score_threshold?: number
+ } = {
+ query: args.query,
+ limit: args.limit ?? 10,
+ }
+ if (args.target_uri) requestBody.target_uri = args.target_uri
+ if (args.score_threshold !== undefined) requestBody.score_threshold = args.score_threshold
+ if (mode === "deep" && sessionId) requestBody.session_id = sessionId
+
+ try {
+ const response = await makeRequest<OpenVikingResponse<SearchResult>>(config, {
+ method: "POST",
+ endpoint: mode === "deep" ? "/api/v1/search/search" : "/api/v1/search/find",
+ body: requestBody,
+ abortSignal: context.abort,
+ })
+
+ const result = unwrapResponse(response) ?? { memories: [], resources: [], skills: [], total: 0 }
+ return formatSearchResults(result, "memsearch", args.query, {
+ mode,
+ query_plan: result.query_plan,
+ })
+ } catch (error: any) {
+ log("ERROR", "memsearch", "Search failed", { error: error.message, args })
+ return `Error: ${error.message}`
+ }
+ },
+ },
+ ),
+ },
+
+ stop: async () => {
+ // Flush any pending debounced save
+ if (saveTimer) {
+ clearTimeout(saveTimer)
+ await saveSessionMap()
+ }
+ // Stop auto-commit scheduler
+ stopAutoCommit()
+ log("INFO", "plugin", "OpenViking Memory Plugin stopped")
+ }
+ }
+}
+
+export default OpenVikingMemoryPlugin