@memoryrelay/plugin-memoryrelay-ai 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alteriom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,465 @@
+# OpenClaw Plugin for MemoryRelay AI
+
+[![npm version](https://img.shields.io/npm/v/@memoryrelay/plugin-memoryrelay-ai)](https://www.npmjs.com/package/@memoryrelay/plugin-memoryrelay-ai)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Long-term memory plugin for OpenClaw agents using [MemoryRelay API](https://api.memoryrelay.net).
+
+## Features
+
+- 🧠 **Semantic Search** — Natural language memory retrieval with vector embeddings
+- 🔄 **Auto-Recall** — Automatically inject relevant memories into agent context
+- 📝 **Auto-Capture** — Intelligently detect and store important information
+- 🤖 **Multi-Agent** — Isolated memory namespaces per agent
+- 🛠️ **CLI Tools** — Manage memories via `openclaw memoryrelay` commands
+- 🔌 **Tool Integration** — Three memory tools for AI agents
+
+## Installation
+
+```bash
+openclaw plugins install @memoryrelay/plugin-memoryrelay-ai
+```
+
+Or via npm:
+
+```bash
+npm install -g @memoryrelay/plugin-memoryrelay-ai
+```
+
+## Quick Start
+
+### 1. Get API Key
+
+Sign up at [memoryrelay.io](https://memoryrelay.io) or use the public demo API.
+
+### 2. Configure
+
+Add to your `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "slots": {
+      "memory": "plugin-memoryrelay-ai"
+    },
+    "entries": {
+      "plugin-memoryrelay-ai": {
+        "enabled": true,
+        "config": {
+          "apiKey": "mem_prod_...",
+          "agentId": "my-agent",
+          "apiUrl": "https://api.memoryrelay.net",
+          "autoRecall": true,
+          "autoCapture": false
+        }
+      }
+    }
+  }
+}
+```
+
+### 3. Restart Gateway
+
+```bash
+openclaw gateway restart
+```
+
+### 4. Test Connection
+
+```bash
+openclaw memoryrelay status
+```
+
+## Usage
+
+### AI Agent Tools
+
+The plugin provides three tools your AI agent can use:
+
+#### `memory_store`
+
+Store a new memory with optional metadata.
+
+> **Note**: The `agent_id` parameter is automatically injected from your config. You don't need to include it.
+
+**Parameters:**
+- `content` (string, required) - Memory content (1-50,000 characters)
+- `metadata` (object, optional) - Key-value metadata (max 10KB when serialized)
+
+**Example:**
+```typescript
+memory_store({
+  content: "User prefers concise bullet-point responses",
+  metadata: { category: "preferences", importance: "high" }
+})
+```
+
+**Returns:** Memory object with `id`, `content`, `agent_id`, `metadata`, `created_at`, `updated_at`
+
+**Rate Limit**: 30 requests per minute
+
+#### `memory_recall`
+
+Search memories using semantic similarity.
+
+**Parameters:**
+- `query` (string, required) - Natural language search query
+- `limit` (number, optional, default: 10) - Maximum results (1-50)
+- `threshold` (number, optional, default: 0.5) - Minimum similarity score (0-1)
+
+**Example:**
+```typescript
+memory_recall({
+  query: "user communication preferences",
+  limit: 5,
+  threshold: 0.7
+})
+```
+
+**Returns:** Array of search results with `memory` object and `score` (0-1):
+```json
+{
+  "results": [
+    {
+      "memory": {
+        "id": "550e8400-...",
+        "content": "User prefers concise bullet-point responses",
+        "metadata": { "category": "preferences" },
+        "created_at": 1707649200
+      },
+      "score": 0.89
+    }
+  ]
+}
+```
+
+#### `memory_forget`
+
+Delete a memory by ID or search query.
+
+**Parameters:**
+- `memoryId` (string, optional) - Memory UUID to delete
+- `query` (string, optional) - Search query (shows candidates if multiple matches)
+
+**Examples:**
+```typescript
+// By ID
+memory_forget({ memoryId: "550e8400-..." })
+
+// By query (interactive if multiple matches)
+memory_forget({ query: "outdated preference" })
+```
+
+**Returns:** Success confirmation
+
+### CLI Commands
+
+```bash
+# Check status
+openclaw memoryrelay status
+
+# List recent memories
+openclaw memoryrelay list --limit 10
+
+# Search memories
+openclaw memoryrelay search "API configuration"
+```
+
+### Auto-Recall
+
+When `autoRecall: true`, relevant memories are automatically injected before each agent turn:
+
+```xml
+<relevant-memories>
+The following memories from MemoryRelay may be relevant:
+- User prefers concise responses
+- Project uses TypeScript with strict mode
+- ...
+</relevant-memories>
+```
+
+**Config:**
+- `recallLimit`: Max memories (default: 5)
+- `recallThreshold`: Min similarity score (default: 0.3)
+
+### Auto-Capture
+
+When `autoCapture: true`, the plugin detects and stores important information automatically.
+
+**Patterns detected:**
+- "remember that..."
+- "my name/email/phone is..."
+- "important: ..."
+- API keys, SSH configs, preferences
+
+**Note:** Disabled by default for privacy.
+
+## Configuration
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `apiKey` | string | ✅ | - | MemoryRelay API key |
+| `agentId` | string | ✅ | - | Unique agent identifier |
+| `apiUrl` | string | No | `api.memoryrelay.net` | API endpoint |
+| `autoRecall` | boolean | No | `true` | Auto-inject memories |
+| `autoCapture` | boolean | No | `false` | Auto-store information |
+| `recallLimit` | number | No | `5` | Max memories to inject |
+| `recallThreshold` | number | No | `0.3` | Similarity threshold (0-1) |
+
+### Environment Variables
+
+Alternatively, use environment variables:
+
+```bash
+export MEMORYRELAY_API_KEY="mem_prod_..."
+export MEMORYRELAY_AGENT_ID="my-agent"
+```
+
+Then reference in config:
+```json
+{
+  "apiKey": "${MEMORYRELAY_API_KEY}",
+  "agentId": "${MEMORYRELAY_AGENT_ID}"
+}
+```
+
+## Architecture
+
+```
+┌─────────────────────┐
+│   OpenClaw Agent    │
+│   (Your AI)         │
+└──────────┬──────────┘
+           │
+           │ Plugin API
+           ↓
+┌─────────────────────┐
+│ @memoryrelay/       │
+│ openclaw-plugin     │
+│ - Tools             │
+│ - CLI               │
+│ - Lifecycle Hooks   │
+└──────────┬──────────┘
+           │
+           │ HTTPS REST
+           ↓
+┌─────────────────────┐
+│ MemoryRelay API     │
+│ api.memoryrelay.net │
+└─────────────────────┘
+```
+
+## API
+
+The plugin includes a TypeScript client for MemoryRelay API:
+
+```typescript
+class MemoryRelayClient {
+  async store(content: string, metadata?: Record<string, string>): Promise<Memory>
+  async search(query: string, limit?: number, threshold?: number): Promise<SearchResult[]>
+  async list(limit?: number, offset?: number): Promise<Memory[]>
+  async get(id: string): Promise<Memory>
+  async delete(id: string): Promise<void>
+  async health(): Promise<{ status: string }>
+}
+```
+
+## Examples
+
+### Basic Usage
+
+```javascript
+// Agent conversation:
+// User: "Remember that I prefer TypeScript over JavaScript"
+// Agent uses: memory_store({ content: "User prefers TypeScript over JavaScript" })
+
+// Later:
+// User: "What language should we use?"
+// Agent uses: memory_recall({ query: "programming language preference" })
+// → Finds previous preference and suggests TypeScript
+```
+
+### CLI Workflow
+
+```bash
+# Store memory
+openclaw memoryrelay store "Project uses Kubernetes on AWS EKS"
+
+# Search later
+openclaw memoryrelay search "kubernetes setup"
+# → Returns relevant infrastructure memories
+
+# List all
+openclaw memoryrelay list --limit 20
+
+# Delete old memory
+openclaw memoryrelay forget --id abc123
+```
+
+## Troubleshooting
+
+### Plugin Not Loading
+
+```bash
+# Check plugin status
+openclaw plugins list | grep memoryrelay
+
+# View config validation
+openclaw doctor
+
+# Check logs
+journalctl -u openclaw-gateway -f
+```
+
+### Connection Failed
+
+```bash
+# Test API directly
+curl https://api.memoryrelay.net/v1/health
+
+# Check API key
+openclaw memoryrelay status
+```
+
+### No Memories Returned
+
+- Check `recallThreshold` (lower = more results)
+- Verify `agentId` matches your API agent
+- Try broader search queries
+
+## Security
+
+- API keys stored in `openclaw.json` (not committed to git)
+- Supports environment variable substitution
+- Auto-capture disabled by default (privacy)
+- No hardcoded credentials
+
+**Best Practices:**
+- Use environment variables in production
+- Never commit `openclaw.json` with real keys
+- Rotate API keys regularly
+- Review auto-captured memories periodically
+
+## Development
+
+### File Structure
+
+```
+openclaw-plugin/
+├── index.ts                  # Plugin implementation
+├── openclaw.plugin.json      # Plugin manifest
+├── package.json              # NPM metadata
+├── LICENSE                   # MIT license
+└── README.md                 # This file
+```
+
+### Testing
+
+```bash
+# Install locally
+openclaw plugins install --link .
+
+# Test tools
+# (via agent conversation or CLI)
+
+# View logs
+tail -f ~/.openclaw/logs/gateway.log
+```
+
+## Related Projects
+
+- **MemoryRelay API** — REST API backend (FastAPI + PostgreSQL)
+- **MCP Server** — [`memoryrelay-mcp-server`](https://www.npmjs.com/package/memoryrelay-mcp-server) for Claude Desktop
+- **Python SDK** — `memoryrelay` on PyPI (coming soon)
+
+## Contributing
+
+Contributions welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests (if applicable)
+4. Update documentation
+5. Submit a pull request
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/memoryrelay/openclaw-plugin/issues)
+- **Docs**: [memoryrelay.io](https://memoryrelay.io)
+- **Discord**: [OpenClaw Community](https://discord.gg/clawd)
+
+## License
+
+MIT © 2026 MemoryRelay
+
+---
+
+## Changelog
+
+### v0.2.0 (2026-02-13) - BREAKING CHANGE
+
+**Package Renamed to Fix Warnings:**
+- Old: `@memoryrelay/openclaw-plugin`
+- New: `@memoryrelay/plugin-memoryrelay-ai`
+- Plugin ID remains: `plugin-memoryrelay-ai`
+- **Why**: Package name must match plugin ID to avoid config warnings
+- **Impact**: No code changes, just package name alignment
+
+**Migration**:
+```bash
+# Uninstall old package
+openclaw plugins uninstall @memoryrelay/openclaw-plugin
+# Install new package
+openclaw plugins install @memoryrelay/plugin-memoryrelay-ai
+```
+
+### v0.1.2 (2026-02-13)
+
+**Bug Fix:**
+- Fixed installation directory mismatch by adding `openclaw.id` to package.json
+- Plugin now correctly installs to `plugin-memoryrelay-ai` directory
+- Resolves "plugin not found" error during `openclaw plugins install`
+
+### v0.1.1 (2026-02-13)
+
+**Breaking Changes:**
+- Plugin ID changed: `memory-memoryrelay` → `plugin-memoryrelay-ai`
+- Update your `openclaw.json` to use new ID in `plugins.slots.memory` and `plugins.entries`
+
+**Documentation Improvements:**
+- ✅ Added agent_id auto-injection documentation
+- ✅ Added size limits (content 1-50K chars, metadata 10KB)
+- ✅ Added rate limit info (30 req/min)
+- ✅ Enhanced tool documentation with return formats
+- ✅ Added response format examples for memory_recall
+
+**Migration Guide:**
+```json
+{
+  "plugins": {
+    "slots": {
+      "memory": "plugin-memoryrelay-ai"  // Changed
+    },
+    "entries": {
+      "plugin-memoryrelay-ai": {  // Changed
+        "enabled": true,
+        "config": { ... }
+      }
+    }
+  }
+}
+```
+
+### v0.1.0 (2026-02-12)
+
+- Initial release
+- Three tools: memory_store, memory_recall, memory_forget
+- Auto-recall and auto-capture features
+- CLI commands
+- Production deployment on 3 agents
+
+---
+
+**Homepage**: https://memoryrelay.io  
+**API**: https://api.memoryrelay.net  
+**Source**: https://github.com/memoryrelay/openclaw-plugin

package/index.ts

@@ -0,0 +1,519 @@
+/**
+ * OpenClaw Memory Plugin - MemoryRelay
+ *
+ * Long-term memory with vector search using MemoryRelay API.
+ * Provides auto-recall and auto-capture via lifecycle hooks.
+ *
+ * API: https://api.memoryrelay.net
+ * Docs: https://memoryrelay.io
+ */
+
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface MemoryRelayConfig {
+  apiKey: string;
+  agentId: string;
+  apiUrl?: string;
+  autoCapture?: boolean;
+  autoRecall?: boolean;
+  recallLimit?: number;
+  recallThreshold?: number;
+}
+
+interface Memory {
+  id: string;
+  content: string;
+  agent_id: string;
+  user_id: string;
+  metadata: Record<string, string>;
+  entities: string[];
+  created_at: number;
+  updated_at: number;
+}
+
+interface SearchResult {
+  memory: Memory;
+  score: number;
+}
+
+// ============================================================================
+// MemoryRelay API Client
+// ============================================================================
+
+class MemoryRelayClient {
+  constructor(
+    private readonly apiKey: string,
+    private readonly agentId: string,
+    private readonly apiUrl: string = "https://api.memoryrelay.net",
+  ) {}
+
+  private async request<T>(
+    method: string,
+    path: string,
+    body?: unknown,
+  ): Promise<T> {
+    const url = `${this.apiUrl}${path}`;
+
+    const response = await fetch(url, {
+      method,
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.apiKey}`,
+        "User-Agent": "openclaw-memory-memoryrelay/0.1.0",
+      },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+
+    if (!response.ok) {
+      const errorData = await response.json().catch(() => ({}));
+      throw new Error(
+        `MemoryRelay API error: ${response.status} ${response.statusText}` +
+          (errorData.message ? ` - ${errorData.message}` : ""),
+      );
+    }
+
+    return response.json();
+  }
+
+  async store(content: string, metadata?: Record<string, string>): Promise<Memory> {
+    return this.request<Memory>("POST", "/v1/memories/memories", {
+      content,
+      metadata,
+      agent_id: this.agentId,
+    });
+  }
+
+  async search(
+    query: string,
+    limit: number = 5,
+    threshold: number = 0.3,
+  ): Promise<SearchResult[]> {
+    const response = await this.request<{ data: SearchResult[] }>(
+      "POST",
+      "/v1/memories/memories/search",
+      {
+        query,
+        limit,
+        threshold,
+        agent_id: this.agentId,
+      },
+    );
+    return response.data || [];
+  }
+
+  async list(limit: number = 20, offset: number = 0): Promise<Memory[]> {
+    const response = await this.request<{ data: Memory[] }>(
+      "GET",
+      `/v1/memories/memories?limit=${limit}&offset=${offset}`,
+    );
+    return response.data || [];
+  }
+
+  async get(id: string): Promise<Memory> {
+    return this.request<Memory>("GET", `/v1/memories/memories/${id}`);
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.request<void>("DELETE", `/v1/memories/memories/${id}`);
+  }
+
+  async health(): Promise<{ status: string }> {
+    return this.request<{ status: string }>("GET", "/v1/health");
+  }
+}
+
+// ============================================================================
+// Pattern Detection (for auto-capture)
+// ============================================================================
+
+const CAPTURE_PATTERNS = [
+  /remember\s+(?:that\s+)?/i,
+  /(?:my|the)\s+(?:name|email|phone|address|preference)/i,
+  /important(?:ly)?[:\s]/i,
+  /always\s+(?:use|prefer|want)/i,
+  /(?:do|don't)\s+(?:like|want|prefer)/i,
+  /(?:api|key|token|password|secret)(?:\s+is)?[:\s]/i,
+  /(?:ssh|server|host|ip|port)(?:\s+is)?[:\s]/i,
+];
+
+function shouldCapture(text: string): boolean {
+  if (text.length < 20 || text.length > 2000) {
+    return false;
+  }
+  return CAPTURE_PATTERNS.some((pattern) => pattern.test(text));
+}
+
+// ============================================================================
+// Plugin Export
+// ============================================================================
+
+export default async function plugin(api: OpenClawPluginApi): Promise<void> {
+  const cfg = api.pluginConfig as MemoryRelayConfig | undefined;
+  if (!cfg?.apiKey || !cfg?.agentId) {
+    api.logger.warn("memory-memoryrelay: missing apiKey or agentId, plugin disabled");
+    return;
+  }
+
+  const client = new MemoryRelayClient(
+    cfg.apiKey,
+    cfg.agentId,
+    cfg.apiUrl || "https://api.memoryrelay.net",
+  );
+
+  // Verify connection on startup
+  try {
+    await client.health();
+    api.logger.info(`memory-memoryrelay: connected to ${cfg.apiUrl || "api.memoryrelay.net"}`);
+  } catch (err) {
+    api.logger.error(`memory-memoryrelay: health check failed: ${String(err)}`);
+    return;
+  }
+
+  // ========================================================================
+  // Tools (using JSON Schema directly)
+  // ========================================================================
+
+  // memory_store tool
+  api.registerTool(
+    {
+      name: "memory_store",
+      description:
+        "Store a new memory in MemoryRelay. Use this to save important information, facts, preferences, or context that should be remembered for future conversations.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          content: {
+            type: "string",
+            description: "The memory content to store. Be specific and include relevant context.",
+          },
+          metadata: {
+            type: "object",
+            description: "Optional key-value metadata to attach to the memory",
+            additionalProperties: { type: "string" },
+          },
+        },
+        required: ["content"],
+      },
+      handler: async ({ content, metadata }: { content: string; metadata?: Record<string, string> }) => {
+        try {
+          const memory = await client.store(content, metadata);
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Memory stored successfully (id: ${memory.id.slice(0, 8)}...)`,
+              },
+            ],
+            details: { id: memory.id, stored: true },
+          };
+        } catch (err) {
+          return {
+            content: [{ type: "text", text: `Failed to store memory: ${String(err)}` }],
+            details: { error: String(err) },
+          };
+        }
+      },
+    },
+    { name: "memory_store" },
+  );
+
+  // memory_recall tool (semantic search)
+  api.registerTool(
+    {
+      name: "memory_recall",
+      description:
+        "Search memories using natural language. Returns the most relevant memories based on semantic similarity.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: {
+            type: "string",
+            description: "Natural language search query",
+          },
+          limit: {
+            type: "number",
+            description: "Maximum results (1-20)",
+            minimum: 1,
+            maximum: 20,
+            default: 5,
+          },
+        },
+        required: ["query"],
+      },
+      handler: async ({ query, limit = 5 }: { query: string; limit?: number }) => {
+        try {
+          const results = await client.search(query, limit, cfg.recallThreshold || 0.3);
+
+          if (results.length === 0) {
+            return {
+              content: [{ type: "text", text: "No relevant memories found." }],
+              details: { count: 0 },
+            };
+          }
+
+          const formatted = results
+            .map(
+              (r) =>
+                `- [${r.score.toFixed(2)}] ${r.memory.content.slice(0, 200)}${
+                  r.memory.content.length > 200 ? "..." : ""
+                }`,
+            )
+            .join("\n");
+
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Found ${results.length} relevant memories:\n${formatted}`,
+              },
+            ],
+            details: {
+              count: results.length,
+              memories: results.map((r) => ({
+                id: r.memory.id,
+                content: r.memory.content,
+                score: r.score,
+              })),
+            },
+          };
+        } catch (err) {
+          return {
+            content: [{ type: "text", text: `Search failed: ${String(err)}` }],
+            details: { error: String(err) },
+          };
+        }
+      },
+    },
+    { name: "memory_recall" },
+  );
+
+  // memory_forget tool
+  api.registerTool(
+    {
+      name: "memory_forget",
+      description: "Delete a memory by ID or search for memories to forget.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          memoryId: {
+            type: "string",
+            description: "Memory ID to delete",
+          },
+          query: {
+            type: "string",
+            description: "Search query to find memory",
+          },
+        },
+      },
+      handler: async ({ memoryId, query }: { memoryId?: string; query?: string }) => {
+        if (memoryId) {
+          try {
+            await client.delete(memoryId);
+            return {
+              content: [{ type: "text", text: `Memory ${memoryId.slice(0, 8)}... deleted.` }],
+              details: { action: "deleted", id: memoryId },
+            };
+          } catch (err) {
+            return {
+              content: [{ type: "text", text: `Delete failed: ${String(err)}` }],
+              details: { error: String(err) },
+            };
+          }
+        }
+
+        if (query) {
+          const results = await client.search(query, 5, 0.5);
+
+          if (results.length === 0) {
+            return {
+              content: [{ type: "text", text: "No matching memories found." }],
+              details: { count: 0 },
+            };
+          }
+
+          // If single high-confidence match, delete it
+          if (results.length === 1 && results[0].score > 0.9) {
+            await client.delete(results[0].memory.id);
+            return {
+              content: [
+                { type: "text", text: `Forgotten: "${results[0].memory.content.slice(0, 60)}..."` },
+              ],
+              details: { action: "deleted", id: results[0].memory.id },
+            };
+          }
+
+          const list = results
+            .map((r) => `- [${r.memory.id.slice(0, 8)}] ${r.memory.content.slice(0, 60)}...`)
+            .join("\n");
+
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Found ${results.length} candidates. Specify memoryId:\n${list}`,
+              },
+            ],
+            details: { action: "candidates", count: results.length },
+          };
+        }
+
+        return {
+          content: [{ type: "text", text: "Provide query or memoryId." }],
+          details: { error: "missing_param" },
+        };
+      },
+    },
+    { name: "memory_forget" },
+  );
+
+  // ========================================================================
+  // CLI Commands
+  // ========================================================================
+
+  api.registerCli(
+    ({ program }) => {
+      const mem = program.command("memoryrelay").description("MemoryRelay memory plugin commands");
+
+      mem
+        .command("status")
+        .description("Check MemoryRelay connection status")
+        .action(async () => {
+          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"}`);
+          } catch (err) {
+            console.error(`Connection failed: ${String(err)}`);
+          }
+        });
+
+      mem
+        .command("list")
+        .description("List recent memories")
+        .option("--limit <n>", "Max results", "10")
+        .action(async (opts) => {
+          const memories = await client.list(parseInt(opts.limit));
+          for (const m of memories) {
+            console.log(`[${m.id.slice(0, 8)}] ${m.content.slice(0, 80)}...`);
+          }
+          console.log(`\nTotal: ${memories.length} memories`);
+        });
+
+      mem
+        .command("search")
+        .description("Search memories")
+        .argument("<query>", "Search query")
+        .option("--limit <n>", "Max results", "5")
+        .action(async (query, opts) => {
+          const results = await client.search(query, parseInt(opts.limit));
+          for (const r of results) {
+            console.log(`[${r.score.toFixed(2)}] ${r.memory.content.slice(0, 80)}...`);
+          }
+        });
+    },
+    { commands: ["memoryrelay"] },
+  );
+
+  // ========================================================================
+  // Lifecycle Hooks
+  // ========================================================================
+
+  // Auto-recall: inject relevant memories before agent starts
+  if (cfg.autoRecall) {
+    api.on("before_agent_start", async (event) => {
+      if (!event.prompt || event.prompt.length < 10) {
+        return;
+      }
+
+      try {
+        const results = await client.search(
+          event.prompt,
+          cfg.recallLimit || 5,
+          cfg.recallThreshold || 0.3,
+        );
+
+        if (results.length === 0) {
+          return;
+        }
+
+        const memoryContext = results
+          .map((r) => `- ${r.memory.content}`)
+          .join("\n");
+
+        api.logger.info?.(
+          `memory-memoryrelay: injecting ${results.length} memories into context`,
+        );
+
+        return {
+          prependContext: `<relevant-memories>\nThe following memories from MemoryRelay may be relevant:\n${memoryContext}\n</relevant-memories>`,
+        };
+      } catch (err) {
+        api.logger.warn?.(`memory-memoryrelay: recall failed: ${String(err)}`);
+      }
+    });
+  }
+
+  // Auto-capture: analyze and store important information after agent ends
+  if (cfg.autoCapture) {
+    api.on("agent_end", async (event) => {
+      if (!event.success || !event.messages || event.messages.length === 0) {
+        return;
+      }
+
+      try {
+        const texts: string[] = [];
+        for (const msg of event.messages) {
+          if (!msg || typeof msg !== "object") continue;
+          const msgObj = msg as Record<string, unknown>;
+          const role = msgObj.role;
+          if (role !== "user" && role !== "assistant") continue;
+
+          const content = msgObj.content;
+          if (typeof content === "string") {
+            texts.push(content);
+          } else if (Array.isArray(content)) {
+            for (const block of content) {
+              if (
+                block &&
+                typeof block === "object" &&
+                "type" in block &&
+                (block as Record<string, unknown>).type === "text" &&
+                "text" in block
+              ) {
+                texts.push((block as Record<string, unknown>).text as string);
+              }
+            }
+          }
+        }
+
+        const toCapture = texts.filter((text) => text && shouldCapture(text));
+        if (toCapture.length === 0) return;
+
+        let stored = 0;
+        for (const text of toCapture.slice(0, 3)) {
+          // Check for duplicates via search
+          const existing = await client.search(text, 1, 0.95);
+          if (existing.length > 0) continue;
+
+          await client.store(text, { source: "auto-capture" });
+          stored++;
+        }
+
+        if (stored > 0) {
+          api.logger.info?.(`memory-memoryrelay: auto-captured ${stored} memories`);
+        }
+      } catch (err) {
+        api.logger.warn?.(`memory-memoryrelay: capture failed: ${String(err)}`);
+      }
+    });
+  }
+
+  api.logger.info?.(
+    `memory-memoryrelay: plugin loaded (autoRecall: ${cfg.autoRecall}, autoCapture: ${cfg.autoCapture})`,
+  );
+}

package/openclaw.plugin.json

@@ -0,0 +1,67 @@
+{
+  "id": "plugin-memoryrelay-ai",
+  "kind": "memory",
+  "name": "MemoryRelay AI",
+  "description": "AI memory service using MemoryRelay API (api.memoryrelay.net)",
+  "version": "0.1.0",
+  "uiHints": {
+    "apiKey": {
+      "label": "MemoryRelay API Key",
+      "sensitive": true,
+      "placeholder": "mem_prod_...",
+      "help": "API key from memoryrelay.io (or use ${MEMORYRELAY_API_KEY})"
+    },
+    "agentId": {
+      "label": "Agent ID",
+      "placeholder": "iris",
+      "help": "Unique identifier for this agent in MemoryRelay"
+    },
+    "apiUrl": {
+      "label": "API URL",
+      "placeholder": "https://api.memoryrelay.net",
+      "advanced": true,
+      "help": "MemoryRelay API endpoint"
+    },
+    "autoCapture": {
+      "label": "Auto-Capture",
+      "help": "Automatically capture important information from conversations"
+    },
+    "autoRecall": {
+      "label": "Auto-Recall",
+      "help": "Automatically inject relevant memories into context"
+    }
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "apiKey": {
+        "type": "string"
+      },
+      "agentId": {
+        "type": "string"
+      },
+      "apiUrl": {
+        "type": "string",
+        "default": "https://api.memoryrelay.net"
+      },
+      "autoCapture": {
+        "type": "boolean",
+        "default": false
+      },
+      "autoRecall": {
+        "type": "boolean",
+        "default": true
+      },
+      "recallLimit": {
+        "type": "number",
+        "default": 5
+      },
+      "recallThreshold": {
+        "type": "number",
+        "default": 0.3
+      }
+    },
+    "required": ["apiKey", "agentId"]
+  }
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@memoryrelay/plugin-memoryrelay-ai",
+  "version": "0.2.0",
+  "description": "OpenClaw memory plugin for MemoryRelay API - long-term memory with semantic search",
+  "type": "module",
+  "main": "index.ts",
+  "keywords": [
+    "openclaw",
+    "plugin",
+    "memory",
+    "memoryrelay",
+    "semantic-search",
+    "vector-search",
+    "ai-memory",
+    "agent-memory"
+  ],
+  "author": "MemoryRelay",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/memoryrelay/openclaw-plugin.git"
+  },
+  "bugs": {
+    "url": "https://github.com/memoryrelay/openclaw-plugin/issues"
+  },
+  "homepage": "https://github.com/memoryrelay/openclaw-plugin#readme",
+  "peerDependencies": {
+    "openclaw": ">=2026.2.0"
+  },
+  "openclaw": {
+    "id": "plugin-memoryrelay-ai",
+    "extensions": ["./"]
+  },
+  "files": [
+    "index.ts",
+    "openclaw.plugin.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}