@memoryrelay/plugin-memoryrelay-ai 0.13.0 → 0.14.0

package/README.md

@@ -1,125 +1,83 @@
-# MemoryRelay AI - OpenClaw Memory Plugin
+# MemoryRelay AI
 
-[![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.26+-blue.svg)](https://openclaw.ai)
+**Engineering Knowledge Platform for OpenClaw**
 
-AI-powered long-term memory for OpenClaw agents. Gives your AI assistant persistent memory, project context, architectural decision records, reusable patterns, and session tracking across conversations.
+Persistent memory, architectural decisions, reusable patterns, and project orchestration for AI agents.
 
-## Features
+[![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.26+-blue.svg)](https://openclaw.ai)
 
-- **39 Tools** covering memories, entities, sessions, decisions, patterns, and projects
-- **8 Gateway Methods** for stats, debugging, and onboarding
-- **Smart Auto-Capture** - Tier-based privacy system with automatic filtering
-- **Daily Memory Stats** - Morning/evening summaries with growth metrics
-- **Debug & Monitoring** - Comprehensive logging, health checks, and performance metrics
-- **Semantic Search** - Vector-based retrieval finds relevant context by meaning
-- **Auto-Recall** - Automatically injects relevant memories into agent context
-- **Project-First Workflow** - Agents receive workflow instructions to start with project context
-- **Decision Records** - Track and check architectural decisions before making new ones
-- **Pattern Library** - Create, search, and adopt reusable conventions across projects
-- **Session Tracking** - Track work sessions with summaries for continuity
-- **External Session IDs** - Multi-agent collaboration and conversation-spanning sessions
-- **Stale Session Cleanup** - Background service automatically closes inactive sessions after a configurable timeout
-- **Sender Identity Tagging** - Multi-agent traceability via auto-injected `sender_id` metadata
-- **Tool Group Filtering** - Enable only the tool groups you need
+## Why MemoryRelay?
 
-## Installation
+MemoryRelay is designed for engineering teams managing complex, long-running projects. It is not general-purpose Q&A memory.
 
-### Requirements
+| Feature | MemoryRelay | Mem0 | OpenClaw-Projects |
+|---------|------------|------|-------------------|
+| Semantic search | Yes (pgvector) | Yes | No |
+| Sessions | Yes (auto-sync with OpenClaw sessions) | No | No |
+| Architectural Decision Records | Yes (record, check, supersede) | No | No |
+| Reusable patterns | Yes (create, adopt, suggest) | No | No |
+| Project orchestration | Yes (10 tools, dependency graphs) | No | Basic |
+| Entities / knowledge graph | Yes (create, link, graph) | Yes | No |
+| Multi-agent collaboration | Yes (agent scoping, subagent tracking) | Limited | No |
+| Auto-capture with privacy tiers | Yes (off/conservative/smart/aggressive) | Basic | No |
+| Direct commands | 15 | ~5 | 0 |
+| Lifecycle hooks | 13 | 0 | 0 |
+| Tools | 39 | ~10 | 0 |
 
-- OpenClaw >= 2026.2.26
-- Node.js >= 20.0.0
-- MemoryRelay API key ([get one at memoryrelay.ai](https://memoryrelay.ai))
+## Quick Start
 
-### Install via OpenClaw CLI
+**1. Install the plugin**
 
 ```bash
 openclaw plugins install @memoryrelay/plugin-memoryrelay-ai
 ```
 
-### Configuration
+**2. Set your API key**
 
 ```bash
-openclaw config set plugins.entries.plugin-memoryrelay-ai.config '{
-  "apiKey": "mem_prod_your_key_here",
-  "agentId": "your-agent-name",
-  "defaultProject": "my-project",
-  "autoRecall": true,
-  "autoCapture": false
-}'
-
-# Or use environment variables
 export MEMORYRELAY_API_KEY="mem_prod_your_key_here"
-export MEMORYRELAY_AGENT_ID="your-agent-name"
-export MEMORYRELAY_DEFAULT_PROJECT="my-project"
-
-# Restart gateway
-openclaw gateway restart
 ```
 
-## Configuration Options
+Or configure inline:
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `apiKey` | string | — | MemoryRelay API key (or `MEMORYRELAY_API_KEY` env var) |
-| `agentId` | string | — | Unique agent identifier (or `MEMORYRELAY_AGENT_ID` env var, or agent name) |
-| `apiUrl` | string | `https://api.memoryrelay.net` | API endpoint (or `MEMORYRELAY_API_URL` env var) |
-| `defaultProject` | string | — | Default project slug applied to sessions, decisions, and memories |
-| `enabledTools` | string | `all` | Comma-separated tool groups: `memory`, `entity`, `agent`, `session`, `decision`, `pattern`, `project`, `health` |
-| `autoRecall` | boolean | `true` | Inject relevant memories into context each turn |
-| `autoCapture` | boolean\|object | `false` | Auto-capture config. Boolean for backward compat, object for tier system: `{enabled, tier, confirmFirst}`. Tiers: `off`, `conservative`, `smart`, `aggressive`. |
-| `recallLimit` | number | `5` | Max memories to inject per turn (1-20) |
-| `recallThreshold` | number | `0.3` | Minimum similarity score for recall (0-1) |
-| `excludeChannels` | string[] | `[]` | Channel IDs to skip auto-recall |
-| `debug` | boolean | `false` | Enable debug logging of API calls |
-| `verbose` | boolean | `false` | Include request/response bodies in debug logs |
-| `logFile` | string | — | Optional file path for persistent debug logs |
-| `maxLogEntries` | number | `100` | Circular buffer size for in-memory logs |
-| `sessionTimeoutMinutes` | number | `120` | Idle time before a session is automatically closed by the cleanup service |
-| `sessionCleanupIntervalMinutes` | number | `30` | How often the background cleanup service checks for stale sessions |
-
-## Smart Auto-Capture
-
-Four capture modes with built-in privacy protection:
-
-| Tier | When to Use | Privacy Level |
-|------|-------------|---------------|
-| `off` | Manual storage only | N/A |
-| `conservative` | Low-risk conversations only | High (blocks most patterns) |
-| `smart` | Balanced automation | Medium (blocks sensitive data) |
-| `aggressive` | Maximum capture | Low (minimal blocking) |
+```bash
+openclaw config set plugins.entries.plugin-memoryrelay-ai.config '{"apiKey": "mem_prod_..."}'
+```
 
-**Privacy Blocklist** — Automatically filters passwords, API keys, credit card numbers, SSNs, and other sensitive data.
+**3. Verify**
 
-```json
-{
-  "autoCapture": {
-    "enabled": true,
-    "tier": "smart",
-    "confirmFirst": 5
-  }
-}
+```
+/memory-health
 ```
 
-With `confirmFirst`, the first N captures show confirmation prompts before running silently.
+Auto-recall and smart auto-capture are enabled by default. The plugin injects relevant memories into context every turn and captures important information automatically.
 
-## Agent Workflow
+## Use Cases
 
-The plugin injects workflow instructions into every agent conversation via the `before_agent_start` hook, guiding the AI to follow a project-first approach:
+**Tech Lead** managing 3+ projects:
+- Record architectural decisions with `decision_record` so future agents (and teammates) check before re-deciding
+- Create reusable patterns (`pattern_create`) and adopt them across projects
+- Use `project_impact` to understand blast radius before cross-cutting changes
 
-1. **Load context** — `project_context(project)` loads hot-tier memories, active decisions, and adopted patterns
-2. **Start session** — `session_start(title, project)` begins tracking work
-3. **Check decisions** — `decision_check(query, project)` before architectural choices
-4. **Find patterns** — `pattern_search(query)` to find established conventions
-5. **Store findings** — `memory_store(content)` for important information
-6. **Record decisions** — `decision_record(title, rationale)` for significant choices
-7. **End session** — `session_end(session_id, summary)` with accomplishment summary
+**DevOps Engineer**:
+- Store infrastructure decisions as ADRs: "Why we chose Fargate over ECS on EC2"
+- Capture runbooks and operational procedures as patterns
+- Track dependencies between services with `project_add_relationship`
 
-For new projects, the agent is guided to call `project_register()` first.
+**Solo Developer**:
+- Build a personal knowledge base of memories, entities, and decisions
+- Use `memory_recall` for semantic search across everything you have stored
+- Link entities to memories for a navigable knowledge graph
 
-## Tool Reference
+**Coding Agent**:
+- Auto-capture learns from conversations without explicit tool calls
+- Pattern adoption ensures consistent code style across sessions
+- Session tracking provides continuity when context windows reset
 
-### Memory Tools (9 tools) — group: `memory`
+## Features -- 39 Tools by Category
+
+### Memory (9 tools) -- group: `memory`
 
 | Tool | Description |
 |------|-------------|
@@ -133,7 +91,7 @@ For new projects, the agent is guided to call `project_register()` first.
 | `memory_context` | Build a token-budget-aware context window from relevant memories |
 | `memory_promote` | Update a memory's importance score and tier |
 
-### Entity Tools (4 tools) — group: `entity`
+### Entity (4 tools) -- group: `entity`
 
 | Tool | Description |
 |------|-------------|
@@ -142,7 +100,7 @@ For new projects, the agent is guided to call `project_register()` first.
 | `entity_list` | List entities with pagination |
 | `entity_graph` | Explore an entity's neighborhood in the knowledge graph |
 
-### Agent Tools (3 tools) — group: `agent`
+### Agent (3 tools) -- group: `agent`
 
 | Tool | Description |
 |------|-------------|
@@ -150,7 +108,7 @@ For new projects, the agent is guided to call `project_register()` first.
 | `agent_create` | Create a new agent (memory namespace) |
 | `agent_get` | Get agent details by ID |
 
-### Session Tools (4 tools) — group: `session`
+### Session (4 tools) -- group: `session`
 
 | Tool | Description |
 |------|-------------|
@@ -159,7 +117,7 @@ For new projects, the agent is guided to call `project_register()` first.
 | `session_recall` | Get session details and timeline |
 | `session_list` | List sessions filtered by project or status |
 
-### Decision Tools (4 tools) — group: `decision`
+### Decision (4 tools) -- group: `decision`
 
 | Tool | Description |
 |------|-------------|
@@ -168,7 +126,7 @@ For new projects, the agent is guided to call `project_register()` first.
 | `decision_supersede` | Replace a decision with a new one (old is marked superseded) |
 | `decision_check` | Semantic search for existing decisions before making new ones |
 
-### Pattern Tools (4 tools) — group: `pattern`
+### Pattern (4 tools) -- group: `pattern`
 
 | Tool | Description |
 |------|-------------|
@@ -177,7 +135,7 @@ For new projects, the agent is guided to call `project_register()` first.
 | `pattern_adopt` | Adopt an existing pattern for a project |
 | `pattern_suggest` | Get pattern suggestions based on project stack |
 
-### Project Tools (10 tools) — group: `project`
+### Project (10 tools) -- group: `project`
 
 | Tool | Description |
 |------|-------------|
@@ -192,7 +150,7 @@ For new projects, the agent is guided to call `project_register()` first.
 | `project_shared_patterns` | Find patterns shared between two projects |
 | `project_context` | Load full project context (memories, decisions, patterns, sessions) |
 
-### Health Tools (1 tool) — group: `health`
+### Health (1 tool) -- group: `health`
 
 | Tool | Description |
 |------|-------------|
@@ -200,145 +158,200 @@ For new projects, the agent is guided to call `project_register()` first.
 
 ## Direct Commands
 
-These slash commands bypass the LLM and execute immediately in the CLI:
+These slash commands bypass the LLM and execute immediately.
+
+### Inspection Commands
 
 | Command | Description |
 |---------|-------------|
-| `/memory-status` | Show connection status, tool counts, and memory stats |
-| `/memory-stats` | Show memory growth, categories, and daily statistics |
-| `/memory-health` | Run health check against the MemoryRelay API |
-| `/memory-logs` | Show recent debug log entries |
-| `/memory-metrics` | Show per-tool performance metrics (call count, success rate, latency) |
+| `/memory-search <query>` | Semantic search across stored memories |
+| `/memory-sessions` | List sessions (optional: `active`, `closed`, or project slug) |
+| `/memory-decisions` | List architectural decisions (optional: project slug) |
+| `/memory-patterns` | List or search patterns (optional: search query) |
+| `/memory-entities` | List entities (optional: entity type filter) |
+| `/memory-projects` | List registered projects |
+| `/memory-agents` | List registered agents |
 
-## Tool Group Filtering
+### Diagnostic Commands
 
-Only enable the groups you need:
+| Command | Description |
+|---------|-------------|
+| `/memory-status` | Connection status, tool counts, and memory stats |
+| `/memory-stats` | Daily statistics (total, growth, top categories) |
+| `/memory-health` | API health check with response time |
+| `/memory-logs` | Recent debug log entries (optional: limit, tool filter) |
+| `/memory-metrics` | Per-tool call counts, success rates, and latency |
+| `/memory-validate` | Production readiness checks |
+| `/memory-config` | Display current plugin configuration |
 
-```json
-{
-  "enabledTools": "memory,session,decision"
-}
-```
+### Management Commands
 
-This enables only the memory (9), session (4), and decision (4) tools — 17 tools instead of 39. Useful for reducing tool clutter when you don't need project graphs or pattern management.
+| Command | Description |
+|---------|-------------|
+| `/memory-forget <id>` | Delete a specific memory by ID |
 
-Available groups: `memory`, `entity`, `agent`, `session`, `decision`, `pattern`, `project`, `health`
+## Configuration Reference
 
-Set to `all` (or omit) to enable everything.
+```bash
+openclaw config set plugins.entries.plugin-memoryrelay-ai.config '{
+  "apiKey": "mem_prod_...",
+  "agentId": "iris",
+  "defaultProject": "my-api",
+  "autoRecall": true,
+  "autoCapture": { "enabled": true, "tier": "smart", "confirmFirst": 5 }
+}'
+```
 
-## Auto-Recall
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `apiKey` | string | -- | MemoryRelay API key |
+| `agentId` | string | -- | Unique agent identifier |
+| `apiUrl` | string | `https://api.memoryrelay.net` | API endpoint |
+| `defaultProject` | string | -- | Default project slug for sessions, decisions, and memories |
+| `enabledTools` | string | `all` | Comma-separated tool groups to enable |
+| `autoRecall` | boolean | `true` | Inject relevant memories into context each turn |
+| `autoCapture` | boolean \| object | `true` | Auto-capture config (see tiers below) |
+| `recallLimit` | number | `5` | Max memories injected per turn (1-20) |
+| `recallThreshold` | number | `0.3` | Minimum similarity score for recall (0-1) |
+| `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) |
+| `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) |
 
-When `autoRecall: true`, relevant memories are automatically injected into agent context each turn:
+### Environment Variables
 
-```
-User: "How should I handle authentication in this project?"
+| Variable | Maps to |
+|----------|---------|
+| `MEMORYRELAY_API_KEY` | `apiKey` |
+| `MEMORYRELAY_AGENT_ID` | `agentId` |
+| `MEMORYRELAY_API_URL` | `apiUrl` |
+| `MEMORYRELAY_DEFAULT_PROJECT` | `defaultProject` |
 
-[Plugin searches memories for "authentication"]
-[Injects workflow instructions + top 5 relevant memories into context]
-Agent uses past decisions and patterns to inform its response
-```
+### Auto-Capture Tiers
 
-## Channel Exclusions
+| Tier | Behavior | Use When |
+|------|----------|----------|
+| `off` | Manual `memory_store` only | Full control, no surprises |
+| `conservative` | Captures only low-risk technical facts | Sensitive environments |
+| `smart` (default) | Balanced automation with privacy blocklist | Most teams |
+| `aggressive` | Maximum capture, minimal filtering | Solo prototyping |
 
-Exclude specific channels from auto-recall and workflow injection:
+The `confirmFirst` setting (default: `5`) prompts for confirmation on the first N captures before running silently. The `blocklist` array accepts regex patterns for content that should never be captured.
 
 ```json
 {
-  "excludeChannels": [
-    "telegram:group_123456",
-    "discord:channel_789012"
-  ]
+  "autoCapture": {
+    "enabled": true,
+    "tier": "smart",
+    "confirmFirst": 5,
+    "blocklist": ["password", "secret", "Bearer\\s+\\S+"],
+    "categories": {
+      "credentials": true,
+      "preferences": true,
+      "technical": true,
+      "personal": false
+    }
+  }
 }
 ```
 
-## Debug & Monitoring
+## Architecture & Privacy
 
-### Enable Debug Mode
+### Data Flow
 
-```json
-{
-  "debug": true,
-  "verbose": false,
-  "maxLogEntries": 1000
-}
+```
+Agent <-> Plugin <-> MemoryRelay API (HTTPS) <-> PostgreSQL + pgvector
 ```
 
-### Gateway Methods
+All data in transit is encrypted via HTTPS. The plugin communicates with `api.memoryrelay.net` using bearer token authentication.
 
-| Method | Purpose | Example |
-|--------|---------|---------|
-| `memoryrelay.logs` | View debug logs | `openclaw gateway-call memoryrelay.logs '{"limit": 50}'` |
-| `memoryrelay.health` | Run health check | `openclaw gateway-call memoryrelay.health` |
-| `memoryrelay.test` | Test individual tools | `openclaw gateway-call memoryrelay.test '{"tool": "memory_store"}'` |
-| `memoryrelay.metrics` | View performance stats | `openclaw gateway-call memoryrelay.metrics` |
-| `memoryrelay.heartbeat` | Daily stats check | `openclaw gateway-call memoryrelay.heartbeat` |
-| `memoryrelay.stats` | CLI stats command | `openclaw gateway-call memoryrelay.stats '{"format": "json"}'` |
-| `memoryrelay.onboarding` | Show onboarding | `openclaw gateway-call memoryrelay.onboarding` |
-| `memory.status` | Plugin status report | `openclaw gateway-call memory.status` |
+### Privacy Controls
 
-### Debug Log Format
+- **Blocklist regex patterns** in auto-capture config filter passwords, API keys, credit card numbers, SSNs, and other sensitive data before storage
+- **Redaction hooks** on `before_message_write` and `tool_result_persist` apply blocklist patterns to messages and tool results before persistence
+- **No credential storage** by default -- the `personal` category requires explicit opt-in
+- **Channel exclusions** prevent auto-recall on sensitive channels
 
-When debug mode is enabled, each API call is logged with timestamp, tool name, duration, and status. Verbose mode additionally captures request/response bodies for deep troubleshooting.
+### Multi-Agent Support
 
-## Privacy & Security
+- Each agent has its own memory namespace via `agentId`
+- Projects, decisions, and patterns are shared across agents
+- Subagent spawning and completion are tracked via lifecycle hooks (`subagent_spawned`, `subagent_ended`)
+- Sender identity is auto-injected into memory metadata for traceability
 
-- **Cloud-Backed** — Memories stored on MemoryRelay servers (HTTPS-encrypted in transit)
-- **API Key Auth** — Bearer token authentication
-- **Agent Isolation** — Memories scoped per agent ID
-- **Channel Filtering** — Exclude sensitive channels from auto-recall
-- **Privacy Blocklist** — Auto-capture filters sensitive data (passwords, SSNs, credit cards, API keys)
-- **Privacy Redaction Hooks** — Sensitive data is also redacted from messages (`before_message_write`) and tool results (`tool_result_persist`) before persistence
-- **Sender Identity** — `memory_store`, `memory_batch_store`, and `decision_record` auto-inject `sender_id` from tool context into metadata for multi-agent traceability
-- **Never store secrets** — Do not store API keys, passwords, or tokens as memories
+### Lifecycle Hooks
 
-## Troubleshooting
+The plugin registers 14 lifecycle hooks:
 
-### Plugin Not Loading
+| Hook | Purpose |
+|------|---------|
+| `before_agent_start` | Auto-recall and workflow injection |
+| `agent_end` | Auto-capture from completed conversations |
+| `session_start` | Auto-create MemoryRelay session from OpenClaw session |
+| `session_end` | Auto-end MemoryRelay session |
+| `before_tool_call` | Reserved for future tool blocking/audit |
+| `after_tool_call` | Session activity tracking and metrics |
+| `before_compaction` | Save key context before compaction |
+| `before_reset` | Save key context before session reset |
+| `message_received` | Activity timestamp updates |
+| `message_sending` | Reserved for future extensibility |
+| `before_message_write` | Privacy redaction |
+| `subagent_spawned` | Track multi-agent collaboration |
+| `subagent_ended` | Store subagent completion summaries |
+| `tool_result_persist` | Privacy redaction on tool results |
 
-```bash
-# Check if installed
-npm list -g @memoryrelay/plugin-memoryrelay-ai
+### Skills
 
-# Reinstall if needed
-openclaw plugins install @memoryrelay/plugin-memoryrelay-ai --force
+The plugin ships with 8 skills providing guided workflows on top of the raw tools:
 
-# Restart gateway
-openclaw gateway restart
+- **Agent-facing**: `memory-workflow`, `decision-tracking`, `pattern-management`, `project-orchestration`, `entity-and-context`
+- **Developer-facing**: `codebase-navigation`, `testing-memoryrelay`, `release-process`
 
-# Check logs for errors
-openclaw gateway logs | grep memoryrelay
-```
+## Troubleshooting
 
-### API Connection Issues
+### Connection refused / API key issues
 
 ```bash
-# Test API directly
-curl -H "X-API-Key: YOUR_KEY" https://api.memoryrelay.net/v1/health
+# Test the API directly
+curl -H "X-API-Key: $MEMORYRELAY_API_KEY" https://api.memoryrelay.net/v1/health
+
+# Check plugin status
+/memory-health
 
-# Check gateway logs
-openclaw gateway logs -f | grep memory-memoryrelay
+# Run full validation
+/memory-validate
 ```
 
-### Auto-Recall Not Working
+If `/memory-health` shows `connected: false`, verify your API key is set correctly via environment variable or config. Keys start with `mem_prod_`.
 
-1. Verify `autoRecall: true` in config
-2. Check memories exist: `openclaw gateway-call memory_list '{"limit": 10}'`
-3. Lower `recallThreshold` (try 0.1) for more results
-4. Check channel not in `excludeChannels`
+### Auto-recall not working
 
-### Known Limitations
+1. Confirm `autoRecall` is `true` (it is by default)
+2. Verify memories exist: run `/memory-search test` to check
+3. Lower `recallThreshold` to `0.1` for broader matching
+4. Check your channel is not in `excludeChannels`
+5. Run `/memory-status` to see the full plugin state
+
+### Debug logging
 
-- `memory_batch_store`: May return 500 errors (use individual `memory_store` as workaround)
-- `memory_context`: Returns 405 Method Not Allowed (use `memory_recall` instead)
+Enable debug mode to see all API calls:
 
-## Skills
+```json
+{
+  "debug": true,
+  "verbose": true,
+  "maxLogEntries": 1000
+}
+```
 
-The plugin ships with 8 skills in `skills/` — 5 agent-facing and 3 developer-facing:
+Then inspect with `/memory-logs` or `/memory-metrics` to identify slow or failing calls.
 
-- **Agent-facing**: `memory-workflow`, `decision-tracking`, `pattern-management`, `project-orchestration`, `entity-and-context`
-- **Developer-facing**: `codebase-navigation`, `testing-memoryrelay`, `release-process`
+### Known Limitations
 
-Skills are loaded via OpenClaw's skill system and provide guided workflows on top of the raw tools.
+- `memory_batch_store`: May return 500 errors on large batches (use individual `memory_store` as workaround)
+- `memory_context`: Returns 405 Method Not Allowed on some API versions (use `memory_recall` instead)
 
 ## Development
 
@@ -347,17 +360,14 @@ git clone https://github.com/memoryrelay/openclaw-plugin.git
 cd openclaw-plugin
 npm install
 npm test
-npm run test:watch
-npm run test:coverage
 ```
 
-## License
-
-MIT License - see [LICENSE](./LICENSE) file
-
 ## Links
 
 - **MemoryRelay**: https://memoryrelay.ai
 - **OpenClaw**: https://docs.openclaw.ai
 - **Repository**: https://github.com/memoryrelay/openclaw-plugin
-- **Issues**: https://github.com/memoryrelay/openclaw-plugin/issues
+
+## License
+
+MIT

package/index.ts

@@ -4586,7 +4586,65 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
   });
 
   // ========================================================================
-  // Direct Commands (5 total) — bypass LLM, execute immediately
+  // Command Argument Parser (v0.14.0)
+  // ========================================================================
+
+  function parseCommandArgs(input: string | undefined): { positional: string[]; flags: Record<string, string | boolean> } {
+    const positional: string[] = [];
+    const flags: Record<string, string | boolean> = {};
+
+    if (!input || input.trim() === "") {
+      return { positional, flags };
+    }
+
+    const tokens: string[] = [];
+    let current = "";
+    let inQuote: string | null = null;
+
+    for (const ch of input) {
+      if (inQuote) {
+        if (ch === inQuote) {
+          inQuote = null;
+        } else {
+          current += ch;
+        }
+      } else if (ch === '"' || ch === "'") {
+        inQuote = ch;
+      } else if (ch === " " || ch === "\t") {
+        if (current) {
+          tokens.push(current);
+          current = "";
+        }
+      } else {
+        current += ch;
+      }
+    }
+    if (current) tokens.push(current);
+
+    let i = 0;
+    while (i < tokens.length) {
+      const token = tokens[i];
+      if (token.startsWith("--")) {
+        const key = token.slice(2);
+        const next = tokens[i + 1];
+        if (next && !next.startsWith("--")) {
+          flags[key] = next;
+          i += 2;
+        } else {
+          flags[key] = true;
+          i += 1;
+        }
+      } else {
+        positional.push(token);
+        i += 1;
+      }
+    }
+
+    return { positional, flags };
+  }
+
+  // ========================================================================
+  // Direct Commands (15 total) — bypass LLM, execute immediately
   // ========================================================================
 
   // /memory-status — Show full plugin status report
@@ -4789,6 +4847,438 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
     },
   });
 
+  // ========================================================================
+  // Direct Commands (10 new — v0.14.0)
+  // ========================================================================
+
+  // /memory-search — Semantic memory search
+  api.registerCommand?.({
+    name: "memory-search",
+    description: "Semantic search across stored memories",
+    requireAuth: true,
+    acceptsArgs: true,
+    handler: async (ctx) => {
+      try {
+        const { positional, flags } = parseCommandArgs(ctx.args);
+        const query = positional[0];
+        if (!query) {
+          return { text: "Usage: /memory-search <query> [--limit 10] [--project slug] [--threshold 0.3]" };
+        }
+        const limit = flags["limit"] ? parseInt(String(flags["limit"]), 10) : 10;
+        const threshold = flags["threshold"] ? parseFloat(String(flags["threshold"])) : 0.3;
+        const project = flags["project"] ? String(flags["project"]) : undefined;
+
+        const results = await client.search(query, limit, threshold, { project });
+        const items: unknown[] = Array.isArray(results) ? results : (results as { data?: unknown[] }).data ?? [];
+
+        if (items.length === 0) {
+          return { text: `No memories found for: "${query}"` };
+        }
+
+        const lines: string[] = [`Memory Search: "${query}"`, "━".repeat(60)];
+        for (const item of items) {
+          const m = item as Record<string, unknown>;
+          const content = String(m["content"] ?? "").slice(0, 120);
+          const score = typeof m["similarity"] === "number" ? `${Math.round(m["similarity"] as number * 100)}%` : "N/A";
+          const category = String(m["category"] ?? "general");
+          const date = m["created_at"] ? new Date(String(m["created_at"])).toLocaleDateString() : "unknown";
+          const id = String(m["id"] ?? "");
+          lines.push(`[${score}] ${content}`);
+          lines.push(`  Category: ${category} | Date: ${date} | ID: ${id}`);
+        }
+
+        return { text: lines.join("\n") };
+      } catch (err) {
+        return { text: `Error: ${String(err)}`, isError: true };
+      }
+    },
+  });
+
+  // /memory-validate — Production readiness check
+  api.registerCommand?.({
+    name: "memory-validate",
+    description: "Run production readiness checks for the MemoryRelay plugin",
+    requireAuth: true,
+    handler: async (_ctx) => {
+      try {
+        const results: Array<{ label: string; status: "PASS" | "FAIL" | "WARN"; detail: string }> = [];
+
+        // 1. API connectivity
+        try {
+          await client.health();
+          results.push({ label: "API connectivity", status: "PASS", detail: "Health endpoint reachable" });
+        } catch (err) {
+          results.push({ label: "API connectivity", status: "FAIL", detail: String(err) });
+        }
+
+        // 2. API health status
+        try {
+          const h = await client.health();
+          const statusStr = String(h.status).toLowerCase();
+          if (VALID_HEALTH_STATUSES.includes(statusStr)) {
+            results.push({ label: "API health", status: "PASS", detail: `Status: ${h.status}` });
+          } else {
+            results.push({ label: "API health", status: "WARN", detail: `Unexpected status: ${h.status}` });
+          }
+        } catch (err) {
+          results.push({ label: "API health", status: "FAIL", detail: String(err) });
+        }
+
+        // 3. Core tools
+        const allTools = Object.values(TOOL_GROUPS).flat();
+        const coreTools = ["memory_store", "memory_recall", "memory_list"];
+        const missing = coreTools.filter((t) => !allTools.includes(t));
+        if (missing.length === 0) {
+          results.push({ label: "Core tools", status: "PASS", detail: "memory_store, memory_recall, memory_list present" });
+        } else {
+          results.push({ label: "Core tools", status: "FAIL", detail: `Missing: ${missing.join(", ")}` });
+        }
+
+        // 4. Auto-recall enabled
+        const autoRecall = cfg?.autoRecall ?? true;
+        results.push({
+          label: "Auto-recall enabled",
+          status: autoRecall ? "PASS" : "WARN",
+          detail: autoRecall ? "Enabled" : "Disabled in config",
+        });
+
+        // 5. Auto-capture enabled
+        results.push({
+          label: "Auto-capture enabled",
+          status: autoCaptureConfig.enabled ? "PASS" : "WARN",
+          detail: autoCaptureConfig.enabled ? `Enabled (tier: ${autoCaptureConfig.tier})` : "Disabled in config",
+        });
+
+        // 6. Memory storage
+        try {
+          await client.list(1);
+          results.push({ label: "Memory storage", status: "PASS", detail: "Storage accessible" });
+        } catch (err) {
+          results.push({ label: "Memory storage", status: "FAIL", detail: String(err) });
+        }
+
+        // 7. Agent ID configured
+        const agentIdOk = agentId && agentId !== "" && agentId !== "default";
+        results.push({
+          label: "Agent ID configured",
+          status: agentIdOk ? "PASS" : "WARN",
+          detail: agentIdOk ? `ID: ${agentId}` : `Agent ID is "${agentId}" — consider setting a unique ID`,
+        });
+
+        const passes = results.filter((r) => r.status === "PASS").length;
+        const failures = results.filter((r) => r.status === "FAIL").length;
+        let grade: string;
+        if (passes === 7) grade = "A+";
+        else if (passes === 6) grade = "A";
+        else if (passes === 5) grade = "B+";
+        else if (passes === 4) grade = "B";
+        else grade = "F";
+
+        const lines: string[] = ["MemoryRelay Production Readiness", "━".repeat(50)];
+        for (const r of results) {
+          lines.push(`[${r.status.padEnd(4)}] ${r.label}: ${r.detail}`);
+        }
+        lines.push("─".repeat(50));
+        lines.push(`Checks passed: ${passes}/7 | Grade: ${grade} | Production ready: ${failures === 0 ? "Yes" : "No"}`);
+
+        return { text: lines.join("\n") };
+      } catch (err) {
+        return { text: `Error: ${String(err)}`, isError: true };
+      }
+    },
+  });
+
+  // /memory-config — Read-only config display
+  api.registerCommand?.({
+    name: "memory-config",
+    description: "Display current MemoryRelay plugin configuration",
+    requireAuth: true,
+    handler: async (_ctx) => {
+      try {
+        const lines: string[] = ["MemoryRelay Configuration", "━".repeat(50)];
+        lines.push(`API URL:             ${apiUrl}`);
+        lines.push(`Agent ID:            ${agentId}`);
+        lines.push(`Default Project:     ${defaultProject || "(none)"}`);
+        lines.push(`Enabled Tools:       ${cfg?.enabledTools ?? "all"}`);
+        lines.push(`Auto-Recall:         ${cfg?.autoRecall ?? true}`);
+        lines.push(`Auto-Capture:        ${autoCaptureConfig.enabled} (tier: ${autoCaptureConfig.tier})`);
+        lines.push(`Recall Limit:        ${cfg?.recallLimit ?? 5}`);
+        lines.push(`Recall Threshold:    ${cfg?.recallThreshold ?? 0.3}`);
+        lines.push(`Exclude Channels:    ${(cfg?.excludeChannels ?? []).join(", ") || "(none)"}`);
+        lines.push(`Session Timeout:     ${cfg?.sessionTimeoutMinutes ?? 120} min`);
+        lines.push(`Cleanup Interval:    ${cfg?.sessionCleanupIntervalMinutes ?? 30} min`);
+        lines.push(`Debug:               ${cfg?.debug ?? false}`);
+        lines.push(`Verbose:             ${cfg?.verbose ?? false}`);
+        lines.push(`Max Log Entries:     ${cfg?.maxLogEntries ?? 100}`);
+        return { text: lines.join("\n") };
+      } catch (err) {
+        return { text: `Error: ${String(err)}`, isError: true };
+      }
+    },
+  });
+
+  // /memory-sessions — List sessions
+  api.registerCommand?.({
+    name: "memory-sessions",
+    description: "List MemoryRelay sessions",
+    requireAuth: true,
+    acceptsArgs: true,
+    handler: async (ctx) => {
+      try {
+        const { flags } = parseCommandArgs(ctx.args);
+        const limit = flags["limit"] ? parseInt(String(flags["limit"]), 10) : 10;
+        const project = flags["project"] ? String(flags["project"]) : undefined;
+        let status: string | undefined = flags["status"] ? String(flags["status"]) : undefined;
+        if (flags["active"]) status = "active";
+
+        const raw = await client.listSessions(limit, project, status);
+        const sessions: unknown[] = Array.isArray(raw) ? raw : (raw as { data?: unknown[] }).data ?? [];
+
+        if (sessions.length === 0) {
+          return { text: "No sessions found." };
+        }
+
+        const lines: string[] = ["MemoryRelay Sessions", "━".repeat(60)];
+        for (const session of sessions) {
+          const s = session as Record<string, unknown>;
+          const sid = String(s["id"] ?? "");
+          const sessionStatus = String(s["status"] ?? "unknown").toUpperCase();
+          const startedAt = s["started_at"] ? new Date(String(s["started_at"])).toLocaleString() : "unknown";
+          let duration = "ongoing";
+          if (s["started_at"] && s["ended_at"]) {
+            const diffMs = new Date(String(s["ended_at"])).getTime() - new Date(String(s["started_at"])).getTime();
+            const diffMin = Math.round(diffMs / 60000);
+            duration = `${diffMin}m`;
+          }
+          const summary = String(s["summary"] ?? "").slice(0, 80);
+          lines.push(`[${sessionStatus}] ${sid}`);
+          lines.push(`  Started: ${startedAt} | Duration: ${duration}`);
+          if (summary) lines.push(`  ${summary}`);
+        }
+
+        return { text: lines.join("\n") };
+      } catch (err) {
+        return { text: `Error: ${String(err)}`, isError: true };
+      }
+    },
+  });
+
+  // /memory-decisions — List decisions
+  api.registerCommand?.({
+    name: "memory-decisions",
+    description: "List architectural decisions stored in MemoryRelay",
+    requireAuth: true,
+    acceptsArgs: true,
+    handler: async (ctx) => {
+      try {
+        const { flags } = parseCommandArgs(ctx.args);
+        const limit = flags["limit"] ? parseInt(String(flags["limit"]), 10) : 10;
+        const project = flags["project"] ? String(flags["project"]) : undefined;
+        const status = flags["status"] ? String(flags["status"]) : undefined;
+        const tags = flags["tags"] ? String(flags["tags"]) : undefined;
+
+        const raw = await client.listDecisions(limit, project, status, tags);
+        const decisions: unknown[] = Array.isArray(raw) ? raw : (raw as { data?: unknown[] }).data ?? [];
+
+        if (decisions.length === 0) {
+          return { text: "No decisions found." };
+        }
+
+        const lines: string[] = ["MemoryRelay Decisions", "━".repeat(60)];
+        for (const decision of decisions) {
+          const d = decision as Record<string, unknown>;
+          const decisionStatus = String(d["status"] ?? "unknown").toUpperCase();
+          const title = String(d["title"] ?? "(untitled)");
+          const date = d["created_at"] ? new Date(String(d["created_at"])).toLocaleDateString() : "unknown";
+          const rationale = String(d["rationale"] ?? "").slice(0, 100);
+          lines.push(`[${decisionStatus}] ${title} (${date})`);
+          if (rationale) lines.push(`  ${rationale}`);
+        }
+
+        return { text: lines.join("\n") };
+      } catch (err) {
+        return { text: `Error: ${String(err)}`, isError: true };
+      }
+    },
+  });
+
+  // /memory-patterns — List/search patterns
+  api.registerCommand?.({
+    name: "memory-patterns",
+    description: "List or search memory patterns",
+    requireAuth: true,
+    acceptsArgs: true,
+    handler: async (ctx) => {
+      try {
+        const { positional, flags } = parseCommandArgs(ctx.args);
+        const query = positional[0] ?? "";
+        const limit = flags["limit"] ? parseInt(String(flags["limit"]), 10) : 10;
+        const category = flags["category"] ? String(flags["category"]) : undefined;
+        const project = flags["project"] ? String(flags["project"]) : undefined;
+
+        const raw = await client.searchPatterns(query, category, project, limit);
+        const patterns: unknown[] = Array.isArray(raw) ? raw : (raw as { data?: unknown[] }).data ?? [];
+
+        if (patterns.length === 0) {
+          return { text: query ? `No patterns found for: "${query}"` : "No patterns found." };
+        }
+
+        const lines: string[] = ["MemoryRelay Patterns", "━".repeat(60)];
+        for (const pattern of patterns) {
+          const p = pattern as Record<string, unknown>;
+          const name = String(p["name"] ?? "(unnamed)");
+          const cat = String(p["category"] ?? "general");
+          const description = String(p["description"] ?? "").slice(0, 100);
+          lines.push(`${name} [${cat}]`);
+          if (description) lines.push(`  ${description}`);
+        }
+
+        return { text: lines.join("\n") };
+      } catch (err) {
+        return { text: `Error: ${String(err)}`, isError: true };
+      }
+    },
+  });
+
+  // /memory-entities — List entities
+  api.registerCommand?.({
+    name: "memory-entities",
+    description: "List entities stored in MemoryRelay",
+    requireAuth: true,
+    acceptsArgs: true,
+    handler: async (ctx) => {
+      try {
+        const { flags } = parseCommandArgs(ctx.args);
+        const limit = flags["limit"] ? parseInt(String(flags["limit"]), 10) : 20;
+
+        const raw = await client.listEntities(limit);
+        const entities: unknown[] = Array.isArray(raw) ? raw : (raw as { data?: unknown[] }).data ?? [];
+
+        if (entities.length === 0) {
+          return { text: "No entities found." };
+        }
+
+        const lines: string[] = ["MemoryRelay Entities", "━".repeat(60)];
+        for (const entity of entities) {
+          const e = entity as Record<string, unknown>;
+          const name = String(e["name"] ?? "(unnamed)");
+          const type = String(e["type"] ?? "unknown");
+          const relationships = Array.isArray(e["relationships"]) ? e["relationships"].length : (typeof e["relationship_count"] === "number" ? e["relationship_count"] : 0);
+          lines.push(`${name} [${type}] (${relationships} relationships)`);
+        }
+
+        return { text: lines.join("\n") };
+      } catch (err) {
+        return { text: `Error: ${String(err)}`, isError: true };
+      }
+    },
+  });
+
+  // /memory-projects — List projects
+  api.registerCommand?.({
+    name: "memory-projects",
+    description: "List projects in MemoryRelay",
+    requireAuth: true,
+    acceptsArgs: true,
+    handler: async (ctx) => {
+      try {
+        const { flags } = parseCommandArgs(ctx.args);
+        const limit = flags["limit"] ? parseInt(String(flags["limit"]), 10) : 20;
+
+        const raw = await client.listProjects(limit);
+        const projects: unknown[] = Array.isArray(raw) ? raw : (raw as { data?: unknown[] }).data ?? [];
+
+        if (projects.length === 0) {
+          return { text: "No projects found." };
+        }
+
+        const lines: string[] = ["MemoryRelay Projects", "━".repeat(60)];
+        for (const project of projects) {
+          const p = project as Record<string, unknown>;
+          const slug = String(p["slug"] ?? "(no-slug)");
+          const description = String(p["description"] ?? "").slice(0, 80);
+          const memoryCount = typeof p["memory_count"] === "number" ? p["memory_count"] : 0;
+          lines.push(`${slug} — ${description || "(no description)"} (${memoryCount} memories)`);
+        }
+
+        return { text: lines.join("\n") };
+      } catch (err) {
+        return { text: `Error: ${String(err)}`, isError: true };
+      }
+    },
+  });
+
+  // /memory-agents — List agents
+  api.registerCommand?.({
+    name: "memory-agents",
+    description: "List agents registered in MemoryRelay",
+    requireAuth: true,
+    acceptsArgs: true,
+    handler: async (ctx) => {
+      try {
+        const { flags } = parseCommandArgs(ctx.args);
+        const limit = flags["limit"] ? parseInt(String(flags["limit"]), 10) : 20;
+
+        const raw = await client.listAgents(limit);
+        const agents: unknown[] = Array.isArray(raw) ? raw : (raw as { data?: unknown[] }).data ?? [];
+
+        if (agents.length === 0) {
+          return { text: "No agents found." };
+        }
+
+        const lines: string[] = ["MemoryRelay Agents", "━".repeat(60)];
+        for (const agent of agents) {
+          const a = agent as Record<string, unknown>;
+          const id = String(a["id"] ?? "(no-id)");
+          const name = String(a["name"] ?? "");
+          const description = String(a["description"] ?? "");
+          lines.push(`${id}${name ? ` (${name})` : ""}${description ? `, ${description}` : ""}`);
+        }
+
+        return { text: lines.join("\n") };
+      } catch (err) {
+        return { text: `Error: ${String(err)}`, isError: true };
+      }
+    },
+  });
+
+  // /memory-forget — Delete a memory by ID
+  api.registerCommand?.({
+    name: "memory-forget",
+    description: "Delete a specific memory by ID",
+    requireAuth: true,
+    acceptsArgs: true,
+    handler: async (ctx) => {
+      const { positional } = parseCommandArgs(ctx.args);
+      const memoryId = positional[0];
+      if (!memoryId) {
+        return { text: "Usage: /memory-forget <memory-id>" };
+      }
+      try {
+        let preview = "";
+        try {
+          const existing = await client.get(memoryId);
+          const m = existing as Record<string, unknown>;
+          preview = String(m["content"] ?? "").slice(0, 120);
+        } catch (_) {
+          // preview unavailable — proceed with delete
+        }
+
+        await client.delete(memoryId);
+
+        const lines = [`Memory deleted: ${memoryId}`];
+        if (preview) lines.push(`Content: ${preview}`);
+        return { text: lines.join("\n") };
+      } catch (err) {
+        const msg = String(err);
+        if (msg.toLowerCase().includes("not found") || msg.includes("404")) {
+          return { text: `Memory not found: ${memoryId}`, isError: true };
+        }
+        return { text: `Error: ${msg}`, isError: true };
+      }
+    },
+  });
+
   // ========================================================================
   // Stale Session Cleanup Service (v0.13.0)
   // ========================================================================

package/openclaw.plugin.json

@@ -2,8 +2,8 @@
   "id": "plugin-memoryrelay-ai",
   "kind": "memory",
   "name": "MemoryRelay AI",
-  "description": "MemoryRelay v0.13.0 - Long-term memory with sessions, decisions, patterns & projects (api.memoryrelay.net)",
-  "version": "0.13.0",
+  "description": "MemoryRelay v0.14.0 - Long-term memory with 15 commands, sessions, decisions, patterns & projects (api.memoryrelay.net)",
+  "version": "0.14.0",
   "uiHints": {
     "apiKey": {
       "label": "MemoryRelay API Key",
@@ -57,6 +57,32 @@
       "placeholder": "30",
       "advanced": true,
       "help": "How often to check for stale sessions (default: 30)"
+    },
+    "recallLimit": {
+      "label": "Recall Limit",
+      "placeholder": "5",
+      "help": "Maximum number of memories to inject per auto-recall (1-20)"
+    },
+    "recallThreshold": {
+      "label": "Recall Threshold",
+      "placeholder": "0.3",
+      "help": "Minimum similarity score for auto-recall (0-1, lower = more results)"
+    },
+    "debug": {
+      "label": "Debug Logging",
+      "help": "Enable debug logging of API calls",
+      "advanced": true
+    },
+    "verbose": {
+      "label": "Verbose Logging",
+      "help": "Include request/response bodies in debug logs (requires debug: true)",
+      "advanced": true
+    },
+    "maxLogEntries": {
+      "label": "Max Log Entries",
+      "placeholder": "100",
+      "help": "Circular buffer size for in-memory debug logs (10-10,000)",
+      "advanced": true
     }
   },
   "configSchema": {
@@ -86,8 +112,34 @@
         "description": "Comma-separated tool groups to enable: memory, entity, agent, session, decision, pattern, project, health, or 'all' (default: all)"
       },
       "autoCapture": {
-        "type": "boolean",
-        "default": false
+        "oneOf": [
+          { "type": "boolean" },
+          {
+            "type": "object",
+            "properties": {
+              "enabled": { "type": "boolean", "default": true },
+              "tier": { "type": "string", "enum": ["off", "conservative", "smart", "aggressive"], "default": "smart" },
+              "confirmFirst": { "type": "number", "default": 5, "minimum": 0, "description": "Number of captures to confirm before auto-accepting" },
+              "categories": {
+                "type": "object",
+                "properties": {
+                  "credentials": { "type": "boolean", "default": true },
+                  "preferences": { "type": "boolean", "default": true },
+                  "technical": { "type": "boolean", "default": true },
+                  "personal": { "type": "boolean", "default": false, "description": "Privacy: personal info requires confirmation" }
+                }
+              },
+              "blocklist": {
+                "type": "array",
+                "items": { "type": "string" },
+                "default": [],
+                "description": "Regex patterns for content to never capture"
+              }
+            }
+          }
+        ],
+        "default": true,
+        "description": "Auto-capture configuration. Use true/false for simple toggle, or object for fine-grained control."
       },
       "autoRecall": {
         "type": "boolean",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@memoryrelay/plugin-memoryrelay-ai",
-  "version": "0.13.0",
-  "description": "OpenClaw memory plugin for MemoryRelay API - sessions, decisions, patterns, projects & semantic search",
+  "version": "0.14.0",
+  "description": "OpenClaw memory plugin for MemoryRelay API - 15 commands, sessions, decisions, patterns, projects & semantic search",
   "type": "module",
   "main": "index.ts",
   "scripts": {