memorix 1.9.6 → 1.9.8

package/docs/INTEGRATIONS.md

@@ -55,7 +55,7 @@ Generated guidance also has scope:
 | Cursor | `memorix setup --agent cursor --global` | Cursor MCP and rules config | Cursor MCP config, `.cursor/rules/memorix.mdc`, skills, and hook guidance | Reload Cursor after setup so it can pick up project config changes. |
 | Grok Build | `memorix setup --agent grok --global` | `~/.grok/hooks/memorix.json` + `~/.grok/AGENTS.md` | Lifecycle hooks on SessionStart, SessionEnd, UserPromptSubmit, PostToolUse, PostToolUseFailure, PreCompact, PostCompact, Stop, and StopFailure, plus Grok project/global guidance | Uses Grok's own JSON hook directory. MCP stays host-owned unless you pass `--mcp http`, which writes `[mcp_servers.memorix]` with `url = "http://localhost:3211/mcp"` in Grok `config.toml`. Global hooks are trusted; project hooks require Grok `/hooks-trust`. Set `GROK_HOME` to use a custom Grok home. The command is `memorix hook --agent grok`. |
 | Gemini CLI | `memorix setup --agent gemini-cli --global` | Gemini CLI extension | Extension under `~/.gemini/extensions/memorix` with MCP, `GEMINI.md` context, hooks, commands, and skills | Antigravity CLI has an official Gemini CLI migration path, but Gemini CLI remains an active standalone Google CLI target. |
-| OpenCode | `memorix setup --agent opencode --global` | OpenCode local plugin file | Global setup writes `~/.config/opencode/plugins/memorix.js`, `~/.config/opencode/opencode.json`, skills, and `AGENTS.md` guidance; repo-local setup writes the `.opencode/` equivalents. | OpenCode loads local plugin and skill files from its config scope. |
+| OpenCode | `memorix setup --agent opencode --global` | OpenCode local plugin file | Global setup writes `~/.config/opencode/plugins/memorix.js`, `~/.config/opencode/opencode.json`, skills, and `AGENTS.md` guidance; repo-local setup writes the `.opencode/` equivalents. | The generated plugin keeps the v1 named export and also exposes the v2 default `id`/`setup` contract. v2 event subscriptions use the host session ID when forwarding hooks. |
 | OpenClaw | `memorix setup --agent openclaw --global` | OpenClaw compatible bundle | `~/.openclaw/extensions/memorix` with `.mcp.json`, skills, and OpenClaw `HOOK.md`/`handler.ts` hook pack | Setup attempts `openclaw plugins install <path> --force` and `openclaw hooks enable memorix` when OpenClaw is available. |
 | Hermes Agent | `memorix setup --agent hermes --global` | Hermes plugin | Hermes home (`%LOCALAPPDATA%\hermes` on native Windows, `~/.hermes` elsewhere, or `HERMES_HOME`), plugin enablement in `config.yaml`, and `mcp_servers.memorix` | The plugin registers hooks, a slash command, a CLI command, and skills through Hermes' plugin context. Existing YAML keys are preserved. |
 | Oh-my-Pi | `memorix setup --agent omp --global` | Oh-my-Pi `omp.extensions` package | `.omp/packages/memorix` or `~/.omp/agent/packages/memorix`, plus `.omp/mcp.json` or `~/.omp/agent/mcp.json` | Setup attempts `omp plugin link <path>`. This target uses Oh-my-Pi's package/extension manifest, not Pi's legacy package manifest. |

package/docs/KNOWN_ISSUES_AND_ROADMAP.md

@@ -1,6 +1,6 @@
 # Memorix 已知边界与路线图
 
-> 最后审阅：2026-09-22（对照 v1.9.6 发布内容）
+> 最后审阅：2026-09-28（对照 v1.9.7 发布内容）
 
 这份文档说明仍然成立的产品边界、风险和方向；它不是发布流水账。
 

package/docs/README.md

@@ -126,7 +126,7 @@ Historical/deep-reference documents may describe older designs. If they conflict
 
 ## Current Product Line
 
-The current product line is **1.9.6**. Multi-device store sync is opt-in and
+The current product line is **1.9.8**. Multi-device store sync is opt-in and
 keeps local SQLite canonical; existing users do not upload anything until they
 configure a relay provider explicitly.
 The authoritative acceptance contract for the current implementation is

package/docs/SETUP.md

@@ -502,7 +502,7 @@ OpenCode can also use a local Memorix plugin generated by setup:
 memorix setup --agent opencode --global
 ```
 
-This writes the OpenCode plugin, skills, MCP config, and `AGENTS.md` guidance in the selected scope.
+This writes the OpenCode plugin, skills, MCP config, and `AGENTS.md` guidance in the selected scope. The generated plugin exports both the legacy v1 hook function and the v2 default `id`/`setup` contract, so OpenCode v1 and v2 can load the same file during the migration window.
 
 Antigravity setup installs a native plugin at `~/.gemini/config/plugins/memorix` for global setup or `.agents/plugins/memorix` for workspace setup. The plugin includes stdio MCP, official hooks, rules, and skills:
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "memorix",
   "mcpName": "io.github.AVIDS2/memorix",
-  "version": "1.9.6",
+  "version": "1.9.8",
   "description": "Local-first shared memory layer for AI coding agents across MCP clients, Git history, reasoning context, and project sessions.",
   "type": "module",
   "sideEffects": false,

package/plugins/antigravity/memorix/plugin.json

@@ -1,4 +1,4 @@
 {
   "name": "memorix",
-  "version": "1.9.6"
+  "version": "1.9.8"
 }

package/plugins/claude/memorix/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "memorix",
-  "version": "1.9.6",
+  "version": "1.9.8",
   "description": "Shared workspace memory for Claude Code and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/codebuddy/memorix/.codebuddy-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.9.6",
+  "version": "1.9.8",
   "description": "Local-first project memory for CodeBuddy Code and other coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/codex/memorix/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.9.6",
+  "version": "1.9.8",
   "description": "Shared workspace memory for Codex and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/copilot/memorix/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.9.6",
+  "version": "1.9.8",
   "description": "Shared local workspace memory for GitHub Copilot CLI and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/gemini/memorix/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.9.6",
+  "version": "1.9.8",
   "mcpServers": {
     "memorix": {
       "command": "memorix",

package/plugins/hermes/memorix/plugin.yaml

@@ -1,5 +1,5 @@
 name: memorix
-version: "1.9.6"
+version: "1.9.8"
 description: Shared workspace memory bridge for Hermes Agent.
 author: AVIDS2
 license: Apache-2.0

package/plugins/omp/memorix/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix-omp-package",
-  "version": "1.9.6",
+  "version": "1.9.8",
   "description": "Memorix shared workspace memory package for Oh-my-Pi.",
   "license": "Apache-2.0",
   "keywords": [

package/plugins/openclaw/memorix/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.9.6",
+  "version": "1.9.8",
   "description": "Shared workspace memory for OpenClaw and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/pi/memorix/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix-pi-package",
-  "version": "1.9.6",
+  "version": "1.9.8",
   "description": "Memorix shared workspace memory package for Pi coding agent.",
   "license": "Apache-2.0",
   "keywords": [

package/server.json

@@ -7,7 +7,7 @@
     "url": "https://github.com/AVIDS2/memorix",
     "source": "github"
   },
-  "version": "1.9.6",
+  "version": "1.9.8",
   "websiteUrl": "https://mem.rglens.com",
   "icons": [
     {
@@ -22,7 +22,7 @@
     {
       "registryType": "npm",
       "identifier": "memorix",
-      "version": "1.9.6",
+      "version": "1.9.8",
       "runtimeHint": "npx",
       "packageArguments": [
         {

package/src/hooks/installers/index.ts

@@ -449,8 +449,10 @@ function generateKiroHookFiles(): Array<{ filename: string; content: string }> {
  * Format: .opencode/plugins/memorix.js — Bun-compatible JS module
  * See: https://opencode.ai/docs/plugins/
  *
- * Plugin contract (verified against official docs Apr 2026):
- *   - Named export: export const MemorixPlugin = async (ctx) => { return { ... } }
+ * Plugin contracts:
+ *   - OpenCode v1: named export `MemorixPlugin` returns an event-hook map.
+ *   - OpenCode v2: default export contains `id` and `setup(ctx)`, with event
+ *     subscriptions and tool hooks registered through the context.
  *   - Return object keys are EVENT NAMES (e.g. "session.created", "file.edited")
  *   - Each key maps to an async handler: (input, output) => { ... }
  *   - Session/file/command events: handler receives ({ event }) for event-style hooks
@@ -464,7 +466,7 @@ function generateKiroHookFiles(): Array<{ filename: string; content: string }> {
  * protocol used by all agents. spawnSync works in both Node.js and Bun
  * runtimes (OpenCode may fall back to Node.js on Windows).
  */
-const OPENCODE_PLUGIN_VERSION = 7;
+const OPENCODE_PLUGIN_VERSION = 8;
 
 const AGENT_SKILL_DIRS: Partial<Record<AgentName, { project: string; global?: string }>> = {
   cursor: { project: path.join('.cursor', 'skills'), global: path.join('.cursor', 'skills') },
@@ -716,6 +718,161 @@ export const MemorixPlugin = async ({ project, client, $, directory, worktree })
     },
   };
 };
+
+/**
+ * OpenCode v2 compatibility layer. Keep this beside the v1 export so one
+ * generated file can be loaded by both host generations during migration.
+ */
+const v2HookCommand = ${hookCommand};
+
+function v2ReportHookFailure(eventName, detail) {
+  if (process.env.MEMORIX_HOOK_DEBUG !== '1') return;
+  console.error('[memorix-plugin] v2 hook delivery failed:', eventName, detail);
+}
+
+function v2EventData(event) {
+  return event && typeof event.data === 'object' && event.data !== null ? event.data : {};
+}
+
+function v2SessionId(event) {
+  const data = v2EventData(event);
+  const value = data.sessionID ?? data.sessionId ?? data.session_id
+    ?? event?.sessionID ?? event?.sessionId;
+  return typeof value === 'string' ? value : '';
+}
+
+function v2RunHook(payload, directory, sessionId) {
+  const nextPayload = { agent: 'opencode', cwd: directory, ...payload };
+  if (sessionId) nextPayload.session_id = sessionId;
+  const eventName = nextPayload.hook_event_name || 'unknown';
+  try {
+    const result = spawnSync(v2HookCommand, ['hook'], {
+      input: JSON.stringify(nextPayload),
+      timeout: 10_000,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      shell: process.platform === 'win32',
+      windowsHide: true,
+    });
+    if (result.status !== 0) {
+      v2ReportHookFailure(eventName, {
+        exit: result.status,
+        stderr: (result.stderr || '').slice(0, 200),
+        error: result.error?.message,
+      });
+    }
+  } catch (error) {
+    v2ReportHookFailure(eventName, error?.message ?? error);
+  }
+}
+
+function v2SessionState(states, sessionId) {
+  const key = sessionId || '__unknown__';
+  let state = states.get(key);
+  if (!state) {
+    state = { pendingText: '', lastDeliveredKey: '' };
+    states.set(key, state);
+  }
+  return state;
+}
+
+function v2FlushAssistant(state, directory, sessionId) {
+  const text = state.pendingText.trim();
+  if (!text || text === state.lastDeliveredKey) return;
+  v2RunHook({ hook_event_name: 'message.updated', ai_response: text }, directory, sessionId);
+  state.lastDeliveredKey = text;
+  state.pendingText = '';
+}
+
+function v2FilePath(file) {
+  if (typeof file === 'string') return file;
+  if (!file || typeof file !== 'object') return '';
+  return file.path ?? file.file ?? file.name ?? '';
+}
+
+function v2HandleEvent(event, directory, states) {
+  if (!event || typeof event !== 'object') return;
+  const type = typeof event.type === 'string' ? event.type : '';
+  const data = v2EventData(event);
+  const sessionId = v2SessionId(event);
+  const state = v2SessionState(states, sessionId);
+  const run = (payload) => v2RunHook(payload, directory, sessionId);
+
+  switch (type) {
+    case 'session.created':
+      run({ hook_event_name: 'session.created' });
+      break;
+    case 'session.text.delta':
+      state.pendingText += typeof data.delta === 'string' ? data.delta : (typeof data.text === 'string' ? data.text : '');
+      break;
+    case 'session.message.updated':
+    case 'message.updated':
+      if (data.role === 'assistant' && typeof data.text === 'string') state.pendingText = data.text;
+      break;
+    case 'session.step.ended': {
+      const files = Array.isArray(data.files) ? data.files : [];
+      for (const file of files) {
+        const filePath = v2FilePath(file);
+        if (filePath) run({ hook_event_name: 'file.edited', file_path: filePath });
+      }
+      if (typeof data.text === 'string') state.pendingText += data.text;
+      break;
+    }
+    case 'session.idle':
+      v2FlushAssistant(state, directory, sessionId);
+      run({ hook_event_name: 'session.idle' });
+      break;
+    case 'session.compacted':
+      run({ hook_event_name: 'session.compacted' });
+      break;
+    default:
+      break;
+  }
+}
+
+function setup(ctx) {
+  const directory = ctx?.location?.directory || ctx?.location?.worktree || process.cwd();
+  const controller = new AbortController();
+  const states = new Map();
+
+  if (ctx?.tool?.hook) {
+    try {
+      Promise.resolve(ctx.tool.hook('execute.after', async (event) => {
+        const sessionId = v2SessionId(event);
+        const data = event && typeof event.input === 'object' ? event.input : {};
+        const tool = event?.tool ?? event?.name ?? '';
+        v2RunHook({
+          hook_event_name: 'tool.execute.after',
+          tool_name: tool,
+          tool_input: data,
+        }, directory, sessionId);
+        if (tool === 'shell') {
+          v2RunHook({
+            hook_event_name: 'command.executed',
+            command: data.command ?? data.cmd ?? '',
+          }, directory, sessionId);
+        }
+      })).catch((error) => v2ReportHookFailure('execute.after', error?.message ?? error));
+    } catch (error) {
+      v2ReportHookFailure('execute.after', error?.message ?? error);
+    }
+  }
+
+  if (ctx?.event?.subscribe) {
+    void (async () => {
+      try {
+        const stream = ctx.event.subscribe({ signal: controller.signal });
+        for await (const event of stream) v2HandleEvent(event, directory, states);
+      } catch (error) {
+        if (!controller.signal.aborted) v2ReportHookFailure('event.subscribe', error?.message ?? error);
+      }
+    })();
+  }
+
+  return () => controller.abort();
+}
+
+export default { id: 'memorix', setup };
 `;
 }
 

package/src/store/orama-store.ts

@@ -909,6 +909,11 @@ export async function searchObservations(options: SearchOptions): Promise<IndexE
   // Fast-tier queries skip embedding entirely (fulltext is sufficient)
   let queryVector: number[] | null = null;
   let embeddingProviderForSearch: EmbeddingProvider | null = null;
+  // Distinct from `embeddingEnabled` (static config): this tracks whether the
+  // current query can use embeddings (provider unavailable, incompatible
+  // dimensions, TLS, network, or timeout). `canUsePersistentLexical` below
+  // must fall back whenever this is true.
+  let embeddingUnavailable = false;
   if (quality !== 'fast' && embeddingEnabled && hasQuery && tier !== 'fast') {
     try {
       const provider = await getEmbeddingProvider();
@@ -916,6 +921,7 @@ export async function searchObservations(options: SearchOptions): Promise<IndexE
         embeddingProviderForSearch = provider;
         const activeVectorDimensions = getVectorDimensions();
         if (activeVectorDimensions !== null && provider.dimensions !== activeVectorDimensions) {
+          embeddingUnavailable = true;
           rememberSearchMode(
             modeKey,
             `fulltext (embedding dimension mismatch: provider ${provider.dimensions}d vs index ${activeVectorDimensions}d)`,
@@ -961,9 +967,12 @@ export async function searchObservations(options: SearchOptions): Promise<IndexE
               : { text: 0.6, vector: 0.4 },
           };
         }
+      } else {
+        embeddingUnavailable = true;
       }
     } catch (error) {
       // Fallback to fulltext if embedding fails or times out
+      embeddingUnavailable = true;
       rememberSearchMode(modeKey, 'fulltext (embedding unavailable)');
       console.error('[memorix] Embedding failed or timed out, falling back to fulltext search');
     }
@@ -972,8 +981,14 @@ export async function searchObservations(options: SearchOptions): Promise<IndexE
   mark('preSearch');
   let results: SearchResultLike | Awaited<ReturnType<typeof search>>;
   const persistentCorpusEligible = await shouldUsePersistentSearch(projectIds, options.projectId);
+  // `embeddingEnabled` alone misses the common case: embedding is configured
+  // (enabled) but the current provider is unavailable, has incompatible
+  // dimensions, or failed at runtime. Without this per-query state, those
+  // failures leave queryVector null AND canUsePersistentLexical false, so
+  // neither the semantic nor lexical persistent path runs — a silent,
+  // deterministic empty result despite the FTS5 index having real matches.
   const canUsePersistentLexical = persistentCorpusEligible && Boolean(hasQuery) && !queryVector &&
-    (quality === 'fast' || tier === 'fast' || !embeddingEnabled);
+    (quality === 'fast' || tier === 'fast' || !embeddingEnabled || embeddingUnavailable);
   let persistent = persistentCorpusEligible && queryVector && embeddingProviderForSearch
     ? await searchPersistentSemantically(options, projectIds, requestLimit, queryVector, embeddingProviderForSearch)
     : canUsePersistentLexical

package/src/store/sqlite-fts.ts

@@ -1,4 +1,5 @@
 import type { Observation } from '../types.js';
+import { isTransientSqliteError } from './sqlite-reliability.js';
 
 /** Rows returned by the derived FTS5 index before normal Observation parsing. */
 export interface SqliteLexicalHit {
@@ -56,31 +57,52 @@ export function buildFtsQuery(query: string): string | null {
   return unique.map((token) => `"${normalizeFtsToken(token)}"`).join(' OR ');
 }
 
+/**
+ * initializeObservationLexicalIndex runs exactly once per db handle (called
+ * from getDatabase's synchronous setup), so a transient cross-process BUSY
+ * here would otherwise be cached as a permanent "unavailable" for that
+ * handle's entire lifetime, with no other call site ever re-checking it.
+ */
+const FTS_INIT_MAX_ATTEMPTS = 3;
+
 /**
  * Create and reconcile the external-content FTS5 index for one SQLite handle.
- * FTS5 is an optional SQLite capability, so an unavailable extension is a
- * normal fallback rather than a reason to make the durable store unusable.
+ * FTS5 is an optional SQLite capability, so a genuinely unavailable extension
+ * is a normal fallback rather than a reason to make the durable store
+ * unusable. Cross-process lock contention (SQLITE_BUSY) is not that case —
+ * it is retried a few times, mirroring the retry already applied to the
+ * write paths in sqlite-store.ts / session-store.ts / mini-skill-store.ts,
+ * since the caller here is synchronous and cannot await retrySqliteBusy.
  */
 export function initializeObservationLexicalIndex(db: any): boolean {
   const known = ftsAvailability.get(db);
   if (known !== undefined) return known;
 
-  try {
-    db.exec(CREATE_OBSERVATION_FTS);
-    const observationCount = Number(db.prepare('SELECT COUNT(*) AS count FROM observations').get()?.count ?? 0);
-    const indexedCount = Number(db.prepare(`SELECT COUNT(*) AS count FROM ${FTS_TABLE}`).get()?.count ?? 0);
-    if (observationCount !== indexedCount) {
-      db.exec(`INSERT INTO ${FTS_TABLE}(${FTS_TABLE}) VALUES ('rebuild')`);
+  let lastError: unknown;
+  for (let attempt = 1; attempt <= FTS_INIT_MAX_ATTEMPTS; attempt++) {
+    try {
+      db.exec(CREATE_OBSERVATION_FTS);
+      const observationCount = Number(db.prepare('SELECT COUNT(*) AS count FROM observations').get()?.count ?? 0);
+      const indexedCount = Number(db.prepare(`SELECT COUNT(*) AS count FROM ${FTS_TABLE}`).get()?.count ?? 0);
+      if (observationCount !== indexedCount) {
+        db.exec(`INSERT INTO ${FTS_TABLE}(${FTS_TABLE}) VALUES ('rebuild')`);
+      }
+      ftsAvailability.set(db, true);
+      return true;
+    } catch (error) {
+      lastError = error;
+      if (!isTransientSqliteError(error) || attempt === FTS_INIT_MAX_ATTEMPTS) break;
+      // better-sqlite3 is synchronous, so there is no await-able delay here;
+      // re-entering db.exec/prepare re-enters SQLite's own busy_timeout wait
+      // (already configured in sqlite-db.ts), which is the retry itself.
     }
-    ftsAvailability.set(db, true);
-    return true;
-  } catch (error) {
-    ftsAvailability.set(db, false);
-    console.warn(
-      `[memorix] SQLite FTS5 unavailable; using the existing search fallback: ${error instanceof Error ? error.message : String(error)}`,
-    );
-    return false;
   }
+
+  ftsAvailability.set(db, false);
+  console.warn(
+    `[memorix] SQLite FTS5 unavailable; using the existing search fallback: ${lastError instanceof Error ? lastError.message : String(lastError)}`,
+  );
+  return false;
 }
 
 export function isObservationLexicalIndexEnabled(db: any): boolean {