MemoryRelay AI

Engineering Knowledge Platform for OpenClaw

Persistent memory, architectural decisions, reusable patterns, and project orchestration for AI agents.

Why MemoryRelay?

MemoryRelay is designed for engineering teams managing complex, long-running projects. It is not general-purpose Q&A memory.

Quick Start

1. Install the plugin

openclaw plugins install @memoryrelay/plugin-memoryrelay-ai

1b. Install native dependencies (for local SQLite cache)

The local cache requires better-sqlite3, which includes native bindings. After plugin installation, run:

cd ~/.openclaw/extensions/plugin-memoryrelay-ai && npm install --omit=dev

Or install globally: npm install -g better-sqlite3

Note: If you skip this step, the plugin still works — it falls back to API-only mode (no local cache).

2. Set your API key

export MEMORYRELAY_API_KEY="mem_prod_your_key_here"

Or configure inline:

openclaw config set plugins.entries.plugin-memoryrelay-ai.config '{"apiKey": "mem_prod_..."}'

3. Verify

/memory-health

Auto-recall and smart auto-capture are enabled by default. The plugin injects relevant memories into context every turn and captures important information automatically.

Use Cases

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

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

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

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

Features -- 42 Tools by Category

Memory (9 tools) -- group: memory

Entity (4 tools) -- group: entity

Agent (3 tools) -- group: agent

Session (4 tools) -- group: session

Decision (4 tools) -- group: decision

Pattern (4 tools) -- group: pattern

Project (10 tools) -- group: project

V2 Async (3 tools) -- group: v2

Health (1 tool) -- group: health

Direct Commands

These slash commands bypass the LLM and execute immediately.

Inspection Commands

Diagnostic Commands

Management Commands

⚠️ Migration Notes

v0.20.0 — autoCapture is now opt-in (breaking change)

autoCapture is disabled by default as of v0.20.0. If you were relying on automatic memory capture, add to your config:

{ "autoCapture": true }

Also updated defaults: recallLimit 5→3, recallThreshold 0.3→0.5.

---

Configuration Reference

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 }
}'

Environment Variables

Local Cache Configuration (v0.17.0+)

{
  "localCache": {
    "enabled": true,
    "dbPath": "~/.openclaw/memoryrelay-cache.db",
    "syncIntervalMinutes": 5,
    "maxLocalMemories": 10000,
    "vectorSearch": { "enabled": false, "provider": "sqlite-vec" },
    "ttl": { "hot": 72, "warm": 168, "cold": 720 }
  }
}

Auto-Capture Tiers

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.

{
  "autoCapture": {
    "enabled": true,
    "tier": "smart",
    "confirmFirst": 5,
    "blocklist": ["password", "secret", "Bearer\\s+\\S+"],
    "categories": {
      "credentials": true,
      "preferences": true,
      "technical": true,
      "personal": false
    }
  }
}

Performance (v0.17.0+)

With local cache enabled (default in v0.17.0), most operations skip API round-trips entirely:

The local cache uses SQLite (better-sqlite3) with FTS5 for full-text search. An optional sqlite-vec extension enables local vector similarity search without API round-trips.

SyncDaemon runs in the background, pushing buffered writes and pulling remote changes on a configurable interval (default: 5 minutes).

Note: v0.17.0 also fixes the · unavailable status display in openclaw status — the plugin now returns real memory counts from the local cache.

Architecture & Privacy

Data Flow

Agent <-> Plugin <-> MemoryRelay API (HTTPS) <-> PostgreSQL + pgvector

All data in transit is encrypted via HTTPS. The plugin communicates with api.memoryrelay.net using bearer token authentication.

Privacy Controls

• 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

Multi-Agent Support

• 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

Lifecycle Hooks

The plugin registers 14 lifecycle hooks:

Skills

The plugin ships with 5 skills providing guided workflows on top of the raw tools:

• memory-workflow — Session lifecycle, storing/retrieving memories
• decision-tracking — ADR management, checking before deciding
• pattern-management — Reusable conventions, search before create
• project-orchestration — Multi-project context loading and impact analysis
• entity-and-context — Knowledge graph, linking entities to memories

Updating

To update to the latest version:

openclaw plugins update plugin-memoryrelay-ai

Or from within a conversation, run /memory-update to see the exact command.

Important: The plugin ID is plugin-memoryrelay-ai (not memory-memoryrelay). Using the wrong ID will fail with "No install record."

After updating, restart the gateway:

openclaw restart

Troubleshooting

Connection refused / API key issues

# Test the API directly
curl -H "X-API-Key: $MEMORYRELAY_API_KEY" https://api.memoryrelay.net/v1/health

# Check plugin status
/memory-health

# Run full validation
/memory-validate

If /memory-health shows connected: false, verify your API key is set correctly via environment variable or config. Keys start with mem_prod_.

Auto-recall not working

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

Enable debug mode to see all API calls:

{
  "debug": true,
  "verbose": true,
  "maxLogEntries": 1000
}

Then inspect with /memory-logs or /memory-metrics to identify slow or failing calls.

Known Limitations

• memory_batch_store: May return 500 errors on large batches (use individual memory_store as workaround)

VPS Setup

Complete guide for running Claude Code with MemoryRelay on a VPS (Ubuntu).

Prerequisites

• Node.js 20+
• OpenClaw installed and configured
• Claude Code CLI installed

1. Install the MCP server

npm install -g @memoryrelay/mcp-server

2. Configure Claude Code settings

Add the MemoryRelay MCP server to ~/.claude/settings.json:

{
  "mcpServers": {
    "MemoryRelay": {
      "command": "memoryrelay-mcp",
      "args": ["--agent-id", "YOUR_AGENT_UUID"],
      "env": {
        "MEMORYRELAY_API_KEY": "mem_prod_your_key_here"
      }
    }
  }
}

Important: agentId must be a UUID obtained from GET /v1/agents — not a name string. Using a name string will cause authentication failures.

3. Install the OpenClaw plugin

openclaw plugins install @memoryrelay/plugin-memoryrelay-ai

4. Add .mcp.json to each project

Create .mcp.json in each project worktree root. This is required for MCP tools to be available in Claude sessions (including claude --print):

{
  "mcpServers": {
    "MemoryRelay": {
      "command": "memoryrelay-mcp",
      "args": ["--agent-id", "YOUR_AGENT_UUID"],
      "env": {
        "MEMORYRELAY_API_KEY": "mem_prod_your_key_here"
      }
    }
  }
}

5. Install Alteriom Claude Skills (optional)

git clone git@github.com:Alteriom/alteriom-claude-skills.git ~/.alteriom-claude-skills

These provide curated skill files for common workflows across projects.

Known Issues

Roadmap

v0.17.0 — Local SQLite cache layer (Epic #62)

• Local SQLite cache for offline-first memory access
• SyncDaemon for background API synchronization
• Local vector search via sqlite-vec
• MemorySearchManager-compatible schema (fixes openclaw status display)
• Issues #63–#72

Development

git clone https://github.com/memoryrelay/openclaw-plugin.git
cd openclaw-plugin
npm install
npm test

Links

• MemoryRelay: https://memoryrelay.ai
• OpenClaw: https://docs.openclaw.ai
• Repository: https://github.com/memoryrelay/openclaw-plugin

License

MIT