@memoryrelay/plugin-memoryrelay-ai 0.16.3 → 0.17.1

package/README.md

@@ -5,7 +5,7 @@
 Persistent memory, architectural decisions, reusable patterns, and project orchestration for AI agents.
 
 [![npm version](https://img.shields.io/npm/v/@memoryrelay/plugin-memoryrelay-ai.svg)](https://www.npmjs.com/package/@memoryrelay/plugin-memoryrelay-ai)
-[![OpenClaw Compatible](https://img.shields.io/badge/OpenClaw-2026.2.0+-blue.svg)](https://openclaw.ai)
+[![OpenClaw Compatible](https://img.shields.io/badge/OpenClaw-2026.3.28+-blue.svg)](https://openclaw.ai)
 
 ## Why MemoryRelay?
 
@@ -34,6 +34,18 @@ MemoryRelay is designed for engineering teams managing complex, long-running pro
 openclaw plugins install @memoryrelay/plugin-memoryrelay-ai
 ```
 
+**1b. Install native dependencies (for local SQLite cache)**
+
+The local cache requires `better-sqlite3`, which includes native bindings. After plugin installation, run:
+
+```bash
+cd ~/.openclaw/extensions/plugin-memoryrelay-ai && npm install --omit=dev
+```
+
+Or install globally: `npm install -g better-sqlite3`
+
+> **Note:** If you skip this step, the plugin still works — it falls back to API-only mode (no local cache).
+
 **2. Set your API key**
 
 ```bash
@@ -226,6 +238,7 @@ openclaw config set plugins.entries.plugin-memoryrelay-ai.config '{
 | `excludeChannels` | string[] | `[]` | Channel IDs to skip auto-recall |
 | `sessionTimeoutMinutes` | number | `120` | Idle time before session auto-close (10-1440) |
 | `sessionCleanupIntervalMinutes` | number | `30` | Stale session check interval (5-360) |
+| `localCache` | object | see below | Local SQLite cache configuration (v0.17.0+) |
 | `debug` | boolean | `false` | Enable debug logging of API calls |
 | `verbose` | boolean | `false` | Include request/response bodies in logs |
 | `maxLogEntries` | number | `100` | Circular buffer size for in-memory logs (10-10000) |
@@ -239,6 +252,33 @@ openclaw config set plugins.entries.plugin-memoryrelay-ai.config '{
 | `MEMORYRELAY_API_URL` | `apiUrl` |
 | `MEMORYRELAY_DEFAULT_PROJECT` | `defaultProject` |
 
+### Local Cache Configuration (v0.17.0+)
+
+```json
+{
+  "localCache": {
+    "enabled": true,
+    "dbPath": "~/.openclaw/memoryrelay-cache.db",
+    "syncIntervalMinutes": 5,
+    "maxLocalMemories": 10000,
+    "vectorSearch": { "enabled": false, "provider": "sqlite-vec" },
+    "ttl": { "hot": 72, "warm": 168, "cold": 720 }
+  }
+}
+```
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `localCache.enabled` | boolean | `true` | Enable local SQLite cache |
+| `localCache.dbPath` | string | `~/.openclaw/memoryrelay-cache.db` | Path to SQLite database |
+| `localCache.syncIntervalMinutes` | number | `5` | Background sync interval (1-60) |
+| `localCache.maxLocalMemories` | number | `10000` | Max memories stored locally |
+| `localCache.vectorSearch.enabled` | boolean | `false` | Enable sqlite-vec vector search |
+| `localCache.vectorSearch.provider` | string | `sqlite-vec` | Vector extension provider |
+| `localCache.ttl.hot` | number | `72` | Hot tier TTL in hours (3 days) |
+| `localCache.ttl.warm` | number | `168` | Warm tier TTL in hours (7 days) |
+| `localCache.ttl.cold` | number | `720` | Cold tier TTL in hours (30 days) |
+
 ### Auto-Capture Tiers
 
 | Tier | Behavior | Use When |
@@ -267,6 +307,22 @@ The `confirmFirst` setting (default: `5`) prompts for confirmation on the first
 }
 ```
 
+## Performance (v0.17.0+)
+
+With local cache enabled (default in v0.17.0), most operations skip API round-trips entirely:
+
+| Operation | API-only (v0.16) | Local cache (v0.17) | Improvement |
+|-----------|------------------|---------------------|-------------|
+| Recall | ~200–500ms | <5ms | 40–100× |
+| Capture | ~150–300ms | <2ms | 75–150× |
+| Status probe | ~100ms | <1ms | 100× |
+
+The local cache uses SQLite (better-sqlite3) with FTS5 for full-text search. An optional sqlite-vec extension enables local vector similarity search without API round-trips.
+
+SyncDaemon runs in the background, pushing buffered writes and pulling remote changes on a configurable interval (default: 5 minutes).
+
+> **Note:** v0.17.0 also fixes the `· unavailable` status display in `openclaw status` — the plugin now returns real memory counts from the local cache.
+
 ## Architecture & Privacy
 
 ### Data Flow
@@ -383,6 +439,92 @@ Then inspect with `/memory-logs` or `/memory-metrics` to identify slow or failin
 
 - `memory_batch_store`: May return 500 errors on large batches (use individual `memory_store` as workaround)
 
+## VPS Setup
+
+Complete guide for running Claude Code with MemoryRelay on a VPS (Ubuntu).
+
+### Prerequisites
+
+- Node.js 20+
+- [OpenClaw](https://openclaw.ai) installed and configured
+- [Claude Code](https://claude.ai/code) CLI installed
+
+### 1. Install the MCP server
+
+```bash
+npm install -g @memoryrelay/mcp-server
+```
+
+### 2. Configure Claude Code settings
+
+Add the MemoryRelay MCP server to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "MemoryRelay": {
+      "command": "memoryrelay-mcp",
+      "args": ["--agent-id", "YOUR_AGENT_UUID"],
+      "env": {
+        "MEMORYRELAY_API_KEY": "mem_prod_your_key_here"
+      }
+    }
+  }
+}
+```
+
+> **Important:** `agentId` must be a UUID obtained from `GET /v1/agents` — not a name string. Using a name string will cause authentication failures.
+
+### 3. Install the OpenClaw plugin
+
+```bash
+openclaw plugins install @memoryrelay/plugin-memoryrelay-ai
+```
+
+### 4. Add `.mcp.json` to each project
+
+Create `.mcp.json` in each project worktree root. This is **required** for MCP tools to be available in Claude sessions (including `claude --print`):
+
+```json
+{
+  "mcpServers": {
+    "MemoryRelay": {
+      "command": "memoryrelay-mcp",
+      "args": ["--agent-id", "YOUR_AGENT_UUID"],
+      "env": {
+        "MEMORYRELAY_API_KEY": "mem_prod_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### 5. Install Alteriom Claude Skills (optional)
+
+```bash
+git clone git@github.com:Alteriom/alteriom-claude-skills.git ~/.alteriom-claude-skills
+```
+
+These provide curated skill files for common workflows across projects.
+
+## Known Issues
+
+| Issue | Status | Workaround |
+|-------|--------|------------|
+| `openclaw status` shows `· unavailable` on OpenClaw 2026.3.28 | Cosmetic — plugin is functional | Fix planned in v0.17.0 (local cache with MemorySearchManager-compatible schema) |
+| `plugins update --all` doesn't reliably update extensions | OpenClaw CLI bug | `rm -rf ~/.openclaw/extensions/plugin-memoryrelay-ai && openclaw plugins install @memoryrelay/plugin-memoryrelay-ai` |
+| `agentId` must be a UUID from `GET /v1/agents` | By design | Do not use agent name strings — retrieve the UUID from the API |
+
+## Roadmap
+
+**v0.17.0** — Local SQLite cache layer ([Epic #62](https://github.com/memoryrelay/openclaw-plugin/issues/62))
+
+- Local SQLite cache for offline-first memory access
+- SyncDaemon for background API synchronization
+- Local vector search via `sqlite-vec`
+- `MemorySearchManager`-compatible schema (fixes `openclaw status` display)
+- Issues [#63](https://github.com/memoryrelay/openclaw-plugin/issues/63)–[#72](https://github.com/memoryrelay/openclaw-plugin/issues/72)
+
 ## Development
 
 ```bash

package/index.ts

@@ -1,6 +1,6 @@
 /**
  * OpenClaw Memory Plugin - MemoryRelay
- * Version: 0.16.3
+ * Version: 0.17.1
  *
  * Long-term memory with vector search using MemoryRelay API.
  * Provides auto-recall and auto-capture via lifecycle hooks.
@@ -14,7 +14,8 @@
  * Docs: https://memoryrelay.ai
  */
 
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
 import { join } from "node:path";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 
@@ -31,6 +32,10 @@ import {
   VALID_HEALTH_STATUSES,
 } from "./src/client/memoryrelay-client.js";
 import { SessionResolver } from "./src/context/session-resolver.js";
+import { LocalCache } from "./src/cache/local-cache.js";
+import { SyncDaemon } from "./src/cache/sync-daemon.js";
+import { PluginMemoryManager } from "./src/cache/memory-manager.js";
+import type { LocalCacheConfig } from "./src/cache/types.js";
 
 // --- Hooks ---
 import { registerBeforeAgentStart } from "./src/hooks/before-agent-start.js";
@@ -98,6 +103,7 @@ interface MemoryRelayConfig {
   maxLogEntries?: number;
   sessionTimeoutMinutes?: number;
   sessionCleanupIntervalMinutes?: number;
+  localCache?: Partial<LocalCacheConfig>;
 }
 
 // ============================================================================
@@ -352,23 +358,64 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
     api.logger.error(`memory-memoryrelay: health check failed: ${String(err)}`);
   }
 
-  // --- Create stub store file so OpenClaw's existsSync checks pass ---
-  // OpenClaw 2026.3.28 scanner proceeds for all memory plugins but then checks
-  // existsSync(store.path) for a local SQLite file. Create a minimal empty file
-  // at the expected path so the scanner doesn't bail with "unavailable".
-  try {
-    const openclawHome = process.env.OPENCLAW_HOME || join(process.env.HOME || "/tmp", ".openclaw");
-    const storeDir = join(openclawHome, "memory");
-    // OpenClaw resolves store path as: ~/.openclaw/memory/{agentId}.sqlite
-    const resolvedAgentId = agentId || "main";
-    const storePath = join(storeDir, `${resolvedAgentId}.sqlite`);
-    if (!existsSync(storePath)) {
+  // --- Local Cache + SyncDaemon (v0.17.0+) ---
+  // Replaces the stub file hack from v0.16.x. LocalCache creates a real SQLite
+  // database at the expected path, satisfying OpenClaw's existsSync scanner and
+  // enabling local-first recall/capture pipelines.
+  const DEFAULT_CACHE_CONFIG: LocalCacheConfig = {
+    enabled: true,
+    dbPath: "",
+    syncIntervalMinutes: 5,
+    maxLocalMemories: 1000,
+    vectorSearch: { enabled: false, provider: "none" },
+    ttl: { hot: 72, warm: 168, cold: 720 },
+  };
+
+  const localCacheConfig: LocalCacheConfig = {
+    ...DEFAULT_CACHE_CONFIG,
+    ...cfg?.localCache,
+    vectorSearch: { ...DEFAULT_CACHE_CONFIG.vectorSearch, ...cfg?.localCache?.vectorSearch },
+    ttl: { ...DEFAULT_CACHE_CONFIG.ttl, ...cfg?.localCache?.ttl },
+  };
+
+  let localCache: LocalCache | null = null;
+  let syncDaemon: SyncDaemon | null = null;
+  let memoryManager: PluginMemoryManager | null = null;
+
+  if (localCacheConfig.enabled) {
+    try {
+      const openclawHome = process.env.OPENCLAW_HOME || join(homedir(), ".openclaw");
+      const resolvedAgentId = agentId || "main";
+      const storeDir = join(openclawHome, "memory");
       mkdirSync(storeDir, { recursive: true });
-      writeFileSync(storePath, Buffer.alloc(0));
-      api.logger.info?.(`memory-memoryrelay: created stub store file at ${storePath}`);
+      const dbPath = join(storeDir, `${resolvedAgentId}.sqlite`);
+      localCacheConfig.dbPath = dbPath;
+
+      localCache = new LocalCache(dbPath, localCacheConfig);
+      syncDaemon = new SyncDaemon(localCache, client, localCacheConfig);
+      syncDaemon.start();
+
+      const vectorAvailable = localCacheConfig.vectorSearch.enabled;
+      memoryManager = new PluginMemoryManager(
+        localCache,
+        syncDaemon,
+        localCacheConfig,
+        vectorAvailable,
+        agentId || "main",
+      );
+
+      // Initial pull on startup (non-blocking)
+      syncDaemon.pull().catch((err) =>
+        api.logger.warn?.(`memory-memoryrelay: initial sync failed: ${String(err)}`),
+      );
+
+      api.logger.info?.(`memory-memoryrelay: local cache initialized at ${dbPath}`);
+    } catch (err) {
+      api.logger.warn?.(`memory-memoryrelay: local cache init failed, falling back to API-only: ${String(err)}`);
+      localCache = null;
+      syncDaemon = null;
+      memoryManager = null;
     }
-  } catch (err) {
-    api.logger.warn?.(`memory-memoryrelay: failed to create stub store file: ${String(err)}`);
   }
 
   // --- Tool enablement filter ---
@@ -398,8 +445,8 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
   // ========================================================================
 
   registerBeforeAgentStart(api, pluginConfig, isToolEnabled, defaultProject);
-  registerBeforePromptBuild(api, pluginConfig, client, sessionResolver);
-  registerAgentEnd(api, pluginConfig, client, sessionResolver);
+  registerBeforePromptBuild(api, pluginConfig, client, sessionResolver, localCache, syncDaemon);
+  registerAgentEnd(api, pluginConfig, client, sessionResolver, localCache, syncDaemon);
   registerSessionLifecycle(api, pluginConfig, client, agentId, defaultProject, sessionResolver);
   registerSubagentHooks(api, pluginConfig, client, agentId, autoCaptureConfig, isBlocklisted);
   registerCompactionHooks(api, client, agentId, blocklist, extractRescueContent);
@@ -425,7 +472,7 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
   // ========================================================================
 
   api.logger.info?.(
-    `memory-memoryrelay: plugin v0.16.3 loaded (${Object.values(TOOL_GROUPS).flat().length} tools, autoRecall: ${pluginConfig.autoRecall}, autoCapture: ${autoCaptureConfig.enabled ? autoCaptureConfig.tier : "off"}, debug: ${debugEnabled})`,
+    `memory-memoryrelay: plugin v0.17.1 loaded (${Object.values(TOOL_GROUPS).flat().length} tools, autoRecall: ${pluginConfig.autoRecall}, autoCapture: ${autoCaptureConfig.enabled ? autoCaptureConfig.tier : "off"}, debug: ${debugEnabled})`,
   );
 
   // ========================================================================
@@ -467,6 +514,29 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
   // `openclaw status` shows memory count, vector info, and provider details
   // instead of "unavailable". OpenClaw 2026.3.28+ calls this for all memory plugins.
   api.registerGatewayMethod?.("memory.probe", async ({ respond }) => {
+    // Use local PluginMemoryManager when available (v0.17.0+)
+    if (memoryManager) {
+      try {
+        const stats = memoryManager.cacheStats();
+        const daemonInfo = memoryManager.getSyncDaemonInfo();
+        respond(true, {
+          available: true,
+          provider: "memoryrelay",
+          memoryCount: stats.totalMemories,
+          tierBreakdown: stats.tierBreakdown,
+          bufferDepth: stats.bufferDepth,
+          syncActive: daemonInfo.running,
+          lastSync: stats.lastSync,
+          vector: { enabled: localCacheConfig.vectorSearch.enabled, dims: 768 },
+          fts: { enabled: true },
+          consecutiveErrors: daemonInfo.errors,
+        });
+        return;
+      } catch (err) {
+        api.logger.warn?.(`memory-memoryrelay: memory.probe local cache failed, falling back to API: ${String(err)}`);
+      }
+    }
+
     try {
       const health = await client.health() as { status: string; embedding_info?: { dimension?: number } };
       const healthStatus = String(health.status).toLowerCase();
@@ -509,6 +579,16 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
     }
   });
 
+  // getMemorySearchManager — exposes the PluginMemoryManager so OpenClaw's
+  // status scanner can call status(), probeVectorAvailability(), and close().
+  api.registerGatewayMethod?.("getMemorySearchManager", async ({ respond }) => {
+    if (memoryManager) {
+      respond(true, { manager: memoryManager });
+    } else {
+      respond(false, { error: "Local cache not initialized" });
+    }
+  });
+
   api.registerGatewayMethod?.("memory.status", async ({ respond }) => {
     try {
       const startTime = Date.now();
@@ -833,7 +913,43 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
 
         if (statusReporter) {
           const report = statusReporter.buildReport(connectionStatus, reportConfig, { total_memories: memoryCount }, TOOL_GROUPS);
-          return { text: StatusReporter.formatReport(report) };
+          let text = StatusReporter.formatReport(report);
+
+          // Append local cache section when available
+          if (memoryManager) {
+            try {
+              const cacheStats = memoryManager.cacheStats();
+              const daemonInfo = memoryManager.getSyncDaemonInfo();
+              const cacheLines: string[] = [];
+              cacheLines.push("LOCAL CACHE");
+              const { hot, warm, cold } = cacheStats.tierBreakdown;
+              cacheLines.push(`  Total:     ${cacheStats.totalMemories} memories (hot: ${hot}, warm: ${warm}, cold: ${cold})`);
+              cacheLines.push(`  Buffer:    ${cacheStats.bufferDepth} entries pending sync`);
+              if (cacheStats.lastSync) {
+                const ago = StatusReporter.formatTimeAgo(new Date(cacheStats.lastSync));
+                cacheLines.push(`  Last sync: ${ago}`);
+              } else {
+                cacheLines.push("  Last sync: never");
+              }
+              const vecLabel = localCacheConfig.vectorSearch.enabled ? "ready (sqlite-vec, 768 dims)" : "disabled";
+              cacheLines.push(`  Vector:    ${vecLabel}`);
+              cacheLines.push("  FTS:       ready");
+              cacheLines.push("");
+              const daemonStatus = daemonInfo.running ? "running" : "stopped";
+              cacheLines.push(`SYNC DAEMON: ${daemonStatus}`);
+              cacheLines.push(`  Interval:  ${daemonInfo.intervalMinutes} minutes`);
+              cacheLines.push(`  Errors:    ${daemonInfo.errors} consecutive`);
+              if (daemonInfo.lastError) {
+                cacheLines.push(`  Last error: ${daemonInfo.lastError}`);
+              }
+              cacheLines.push("");
+              text += cacheLines.join("\n");
+            } catch {
+              // cache stats unavailable — skip section
+            }
+          }
+
+          return { text };
         }
         return { text: `MemoryRelay: ${isConnected ? "connected" : "disconnected"} | Endpoint: ${apiUrl} | Memories: ${memoryCount} | Agent: ${agentId}` };
       } catch (err) {
@@ -1336,6 +1452,20 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
     },
   });
 
+  // ========================================================================
+  // Local Cache Cleanup Service
+  // ========================================================================
+
+  if (localCache || syncDaemon) {
+    api.registerService({
+      id: "memoryrelay-cache-cleanup",
+      stop: async () => {
+        syncDaemon?.stop();
+        localCache?.close();
+      },
+    });
+  }
+
   // ========================================================================
   // Stale Session Cleanup Service
   // ========================================================================

package/openclaw.plugin.json

@@ -2,8 +2,8 @@
   "id": "plugin-memoryrelay-ai",
   "kind": "memory",
   "name": "MemoryRelay AI",
-  "description": "MemoryRelay v0.16.3 - Long-term memory with pipeline architecture, 42 tools, 17 commands, V2 async, sessions, decisions, patterns & projects (api.memoryrelay.net)",
-  "version": "0.16.3",
+  "description": "MemoryRelay v0.17.1 - Long-term memory with pipeline architecture, 42 tools, 17 commands, V2 async, sessions, decisions, patterns & projects (api.memoryrelay.net)",
+  "version": "0.17.1",
   "uiHints": {
     "apiKey": {
       "label": "MemoryRelay API Key",
@@ -225,6 +225,47 @@
           }
         }
       },
+      "localCache": {
+        "type": "object",
+        "description": "Local SQLite cache for fast, offline-capable memory access",
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "default": true,
+            "description": "Enable local SQLite cache layer"
+          },
+          "syncIntervalMinutes": {
+            "type": "number",
+            "default": 5,
+            "minimum": 1,
+            "maximum": 60,
+            "description": "How often to sync with the API (minutes)"
+          },
+          "maxLocalMemories": {
+            "type": "number",
+            "default": 1000,
+            "minimum": 100,
+            "maximum": 10000,
+            "description": "Maximum number of memories to keep locally"
+          },
+          "vectorSearch": {
+            "type": "object",
+            "properties": {
+              "enabled": { "type": "boolean", "default": true },
+              "provider": { "type": "string", "default": "sqlite-vec" }
+            }
+          },
+          "ttl": {
+            "type": "object",
+            "description": "Time-to-live per tier (hours)",
+            "properties": {
+              "hot": { "type": "number", "default": 72 },
+              "warm": { "type": "number", "default": 168 },
+              "cold": { "type": "number", "default": 720 }
+            }
+          }
+        }
+      },
       "ranking": {
         "type": "object",
         "properties": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memoryrelay/plugin-memoryrelay-ai",
-  "version": "0.16.3",
+  "version": "0.17.1",
   "description": "OpenClaw memory plugin for MemoryRelay API - 42 tools, 17 commands, V2 async, sessions, decisions, patterns, projects & semantic search",
   "type": "module",
   "main": "index.ts",
@@ -33,6 +33,7 @@
     "openclaw": ">=2026.2.0"
   },
   "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^25.3.5",
     "@vitest/coverage-v8": "^1.2.0",
     "typescript": "^5.9.3",
@@ -51,7 +52,16 @@
     "src/",
     "skills/"
   ],
+  "bundledDependencies": [
+    "better-sqlite3"
+  ],
   "engines": {
     "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "better-sqlite3": "^12.8.0"
+  },
+  "optionalDependencies": {
+    "sqlite-vec": "^0.1.0"
   }
 }