@memoryrelay/plugin-memoryrelay-ai 0.2.4 → 0.4.0

package/README.md

@@ -13,6 +13,7 @@ Long-term memory plugin for OpenClaw agents using [MemoryRelay API](https://api.
 - 🤖 **Multi-Agent** — Isolated memory namespaces per agent
 - 🛠️ **CLI Tools** — Manage memories via `openclaw memoryrelay` commands
 - 🔌 **Tool Integration** — Three memory tools for AI agents
+- ✅ **Status Reporting** — Real-time availability and connection status in `openclaw status`
 
 ## Installation
 
@@ -28,6 +29,61 @@ npm install -g @memoryrelay/plugin-memoryrelay-ai
 
 ## Quick Start
 
+### 1. Install the plugin
+
+```bash
+openclaw plugins install @memoryrelay/plugin-memoryrelay-ai
+```
+
+### 2. Configure API credentials
+
+**Option A: Config file** (recommended)
+```bash
+cat ~/.openclaw/openclaw.json | jq '.plugins.entries."plugin-memoryrelay-ai".config = {
+  "apiKey": "YOUR_API_KEY",
+  "agentId": "YOUR_AGENT_ID",
+  "autoRecall": true,
+  "autoCapture": false
+}' > /tmp/config.json && \
+mv /tmp/config.json ~/.openclaw/openclaw.json && \
+chmod 600 ~/.openclaw/openclaw.json
+```
+
+**Option B: Environment variables**
+```bash
+export MEMORYRELAY_API_KEY="YOUR_API_KEY"
+export MEMORYRELAY_AGENT_ID="YOUR_AGENT_ID"
+```
+
+### 3. Restart the gateway
+
+```bash
+openclaw gateway restart
+```
+
+### 4. Verify it's working
+
+```bash
+openclaw status
+# When API is reachable (example output):
+# Memory | enabled (plugin plugin-memoryrelay-ai) · available
+#
+# When API is down (example output):
+# Memory | enabled (plugin plugin-memoryrelay-ai) · unavailable
+# (Note: Exact format depends on your OpenClaw version)
+
+# Check plugin-specific status
+openclaw memoryrelay status
+# Shows: API connection, agent ID, endpoint
+
+# Check logs
+journalctl -u openclaw-gateway --since '1 minute ago' | grep memory-memoryrelay
+# Example output: "memory-memoryrelay: connected to https://api.memoryrelay.net"
+# (URL will vary if you configured a custom apiUrl)
+```
+
+Get your API key from [memoryrelay.ai](https://memoryrelay.ai).
+
 ### 1. Get API Key
 
 Sign up at [memoryrelay.io](https://memoryrelay.io) or use the public demo API.
@@ -152,6 +208,30 @@ memory_forget({ query: "outdated preference" })
 
 **Returns:** Success confirmation
 
+### Status Monitoring
+
+The plugin reports its availability and connection status to OpenClaw:
+
+```bash
+# Check overall status (shows plugin availability)
+openclaw status
+# Shows: Memory | enabled (plugin plugin-memoryrelay-ai) · available
+
+# Check plugin-specific status (MemoryRelay custom command)
+openclaw memoryrelay status
+# Shows: API connection, agent ID, endpoint
+```
+
+**Status Information Reported:**
+- **Available/Unavailable** — Whether the plugin can be used
+- **Connected** — Whether the MemoryRelay API is reachable
+- **Memory Count** — Total memories stored for this agent (if stats endpoint exists)
+- **Vector Enabled** — Semantic search capability (always true)
+- **Endpoint** — API URL being used
+- **Agent ID** — Current agent identifier
+
+When the API is unreachable, status shows "unavailable" with error details.
+
 ### CLI Commands
 
 ```bash
@@ -396,6 +476,47 @@ MIT © 2026 MemoryRelay
 
 ## Changelog
 
+### v0.4.0 (2026-02-13) - Status Reporting
+
+**New Features:**
+- ✅ Status reporting via `memory.status` gateway RPC method
+- ✅ Plugin now reports "available" in `openclaw status` when API is reachable
+- ✅ Memory count reporting (via optional `/v1/stats` API endpoint)
+- ✅ Vector availability reporting for semantic search
+- ✅ Detailed status information: connected state, endpoint, agent ID, memory count
+
+**Fixes:**
+- ✅ Plugin no longer shows as "unavailable" in `openclaw status` when functional
+- ✅ Status accurately reflects API connection state
+
+**Technical Improvements:**
+- ✅ Extracted constants for maintainability (`DEFAULT_API_URL`, `VALID_HEALTH_STATUSES`)
+- ✅ Case-insensitive health status validation
+- ✅ Proper type safety with nullish coalescing operators
+- ✅ Graceful handling of missing stats endpoint (backwards compatible)
+
+**Backwards Compatibility:**
+- Fully compatible with older OpenClaw versions (uses optional chaining)
+- Gracefully handles missing `/v1/stats` endpoint
+
+### v0.3.0 (2026-02-13) - Better Installation UX
+
+**Improved Installation Experience:**
+- ✅ API key can now come from `MEMORYRELAY_API_KEY` env var
+- ✅ Agent ID can come from `MEMORYRELAY_AGENT_ID` env var or defaults to "default"
+- ✅ Clear error message with setup instructions when config is missing
+- ✅ Comprehensive installation guide in README
+- ✅ No more silent failures - helpful error messages
+
+**Breaking Change:**
+- Debug logging removed (replaced with helpful error messages)
+
+**Migration:**
+Works out of the box with env vars, or add config after install:
+```bash
+cat ~/.openclaw/openclaw.json | jq '.plugins.entries."plugin-memoryrelay-ai".config = {"apiKey": "YOUR_KEY", "agentId": "YOUR_AGENT"}' > /tmp/config.json && mv /tmp/config.json ~/.openclaw/openclaw.json
+```
+
 ### v0.2.4 (2026-02-13)
 
 **Debug Logging:**

package/index.ts

@@ -10,6 +10,13 @@
 
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 
+// ============================================================================
+// Constants
+// ============================================================================
+
+const DEFAULT_API_URL = "https://api.memoryrelay.net";
+const VALID_HEALTH_STATUSES = ["ok", "healthy", "up"];
+
 // ============================================================================
 // Types
 // ============================================================================
@@ -48,7 +55,7 @@ class MemoryRelayClient {
   constructor(
     private readonly apiKey: string,
     private readonly agentId: string,
-    private readonly apiUrl: string = "https://api.memoryrelay.net",
+    private readonly apiUrl: string = DEFAULT_API_URL,
   ) {}
 
   private async request<T>(
@@ -124,6 +131,17 @@ class MemoryRelayClient {
   async health(): Promise<{ status: string }> {
     return this.request<{ status: string }>("GET", "/v1/health");
   }
+
+  async stats(): Promise<{ total_memories: number; last_updated?: string }> {
+    const response = await this.request<{ data: { total_memories: number; last_updated?: string } }>(
+      "GET",
+      `/v1/stats?agent_id=${encodeURIComponent(this.agentId)}`,
+    );
+    return {
+      total_memories: response.data?.total_memories ?? 0,
+      last_updated: response.data?.last_updated,
+    };
+  }
 }
 
 // ============================================================================
@@ -159,36 +177,87 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
   
   const cfg = api.pluginConfig as MemoryRelayConfig | undefined;
   
-  if (!cfg) {
-    api.logger.error("memory-memoryrelay: pluginConfig is null or undefined");
-    return;
-  }
+  // Try to get config from multiple sources
+  const apiKey = cfg?.apiKey || process.env.MEMORYRELAY_API_KEY;
+  const agentId = cfg?.agentId || process.env.MEMORYRELAY_AGENT_ID || "default";
   
-  if (!cfg.apiKey) {
-    api.logger.error(`memory-memoryrelay: missing apiKey in config. Config keys: ${Object.keys(cfg).join(', ')}`);
+  if (!apiKey) {
+    api.logger.error(
+      "memory-memoryrelay: missing API key. Configure in one of these ways:\n" +
+      "  1. Add to config: plugins.entries.\"plugin-memoryrelay-ai\".config.apiKey\n" +
+      "  2. Set environment variable: MEMORYRELAY_API_KEY\n" +
+      "  3. Run: cat ~/.openclaw/openclaw.json | jq '.plugins.entries.\"plugin-memoryrelay-ai\".config = {\"apiKey\": \"YOUR_KEY\", \"agentId\": \"YOUR_AGENT\"}' > /tmp/config.json && mv /tmp/config.json ~/.openclaw/openclaw.json\n" +
+      "Get your API key from: https://memoryrelay.ai"
+    );
     return;
   }
   
-  if (!cfg.agentId) {
-    api.logger.error(`memory-memoryrelay: missing agentId in config. Config keys: ${Object.keys(cfg).join(', ')}`);
-    return;
-  }
+  api.logger.info(`memory-memoryrelay: using agentId: ${agentId}`);
 
-  const client = new MemoryRelayClient(
-    cfg.apiKey,
-    cfg.agentId,
-    cfg.apiUrl || "https://api.memoryrelay.net",
-  );
+  const apiUrl = cfg?.apiUrl || DEFAULT_API_URL;
+  const client = new MemoryRelayClient(apiKey, agentId, apiUrl);
 
   // Verify connection on startup
   try {
     await client.health();
-    api.logger.info(`memory-memoryrelay: connected to ${cfg.apiUrl || "api.memoryrelay.net"}`);
+    api.logger.info(`memory-memoryrelay: connected to ${apiUrl}`);
   } catch (err) {
     api.logger.error(`memory-memoryrelay: health check failed: ${String(err)}`);
     return;
   }
 
+  // ========================================================================
+  // Status Reporting (for openclaw status command)
+  // ========================================================================
+
+  // Register gateway RPC method for status probing
+  // This allows OpenClaw's status command to query plugin availability
+  api.registerGatewayMethod?.("memory.status", async ({ respond }) => {
+    try {
+      const health = await client.health();
+      let memoryCount = 0;
+      
+      // Try to get stats if the endpoint exists
+      try {
+        const stats = await client.stats();
+        memoryCount = stats.total_memories;
+      } catch (statsErr) {
+        // Stats endpoint may not exist yet - that's okay, just report 0
+        api.logger.debug?.(`memory-memoryrelay: stats endpoint unavailable: ${String(statsErr)}`);
+      }
+      
+      // Consider API connected if health check succeeds with any recognized status
+      const healthStatus = String(health.status).toLowerCase();
+      const isConnected = VALID_HEALTH_STATUSES.includes(healthStatus);
+      
+      respond(true, {
+        available: true,
+        connected: isConnected,
+        endpoint: apiUrl,
+        memoryCount: memoryCount,
+        agentId: agentId,
+        // OpenClaw checks status.vector.available for memory plugins
+        vector: {
+          available: true,
+          enabled: true,
+        },
+      });
+    } catch (err) {
+      respond(true, {
+        available: false,
+        connected: false,
+        error: String(err),
+        endpoint: apiUrl,
+        agentId: agentId,
+        // Report vector as unavailable when API fails
+        vector: {
+          available: false,
+          enabled: true,
+        },
+      });
+    }
+  });
+
   // ========================================================================
   // Tools (using JSON Schema directly)
   // ========================================================================
@@ -401,8 +470,8 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
           try {
             const health = await client.health();
             console.log(`Status: ${health.status}`);
-            console.log(`Agent ID: ${cfg.agentId}`);
-            console.log(`API: ${cfg.apiUrl || "https://api.memoryrelay.net"}`);
+            console.log(`Agent ID: ${agentId}`);
+            console.log(`API: ${apiUrl}`);
           } catch (err) {
             console.error(`Connection failed: ${String(err)}`);
           }

package/openclaw.plugin.json

@@ -3,7 +3,7 @@
   "kind": "memory",
   "name": "MemoryRelay AI",
   "description": "AI memory service using MemoryRelay API (api.memoryrelay.net)",
-  "version": "0.2.4",
+  "version": "0.4.0",
   "uiHints": {
     "apiKey": {
       "label": "MemoryRelay API Key",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memoryrelay/plugin-memoryrelay-ai",
-  "version": "0.2.4",
+  "version": "0.4.0",
   "description": "OpenClaw memory plugin for MemoryRelay API - long-term memory with semantic search",
   "type": "module",
   "main": "index.ts",