@memoryrelay/plugin-memoryrelay-ai 0.12.9 → 0.12.11

package/README.md

@@ -8,16 +8,17 @@ AI-powered long-term memory for OpenClaw agents. Gives your AI assistant persist
 ## Features
 
 - **39 Tools** covering memories, entities, sessions, decisions, patterns, and projects
-- **6 Gateway Methods** for stats, debugging, and onboarding (v0.8.0+, Phase 1)
-- **Smart Auto-Capture** - Tier-based privacy system with automatic filtering (v0.12.0+)
-- **Daily Memory Stats** - Morning/evening summaries with growth metrics (v0.12.0+)
-- **Debug & Monitoring** - Comprehensive logging, health checks, and performance metrics (v0.8.0+)
+- **6 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
 - **Tool Group Filtering** - Enable only the tool groups you need
 
 ## Installation
@@ -64,39 +65,27 @@ openclaw gateway restart
 | `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 | `{enabled: true, tier: "smart"}` | Auto-capture config. Boolean for backward compat, object for tier system: `{enabled, tier, confirmFirst}`. Tiers: `off`, `conservative`, `smart`, `aggressive`. See Phase 1 features below. |
+| `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 (v0.8.0+) |
-| `verbose` | boolean | `false` | Include request/response bodies in debug logs (v0.8.0+) |
-| `logFile` | string | — | Optional file path for persistent debug logs (v0.8.0+) |
-| `maxLogEntries` | number | `100` | Circular buffer size for in-memory logs (v0.8.0+) |
+| `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 |
 
-# Phase 1 Section for README
+## Smart Auto-Capture
 
-## Phase 1: Zero-Friction Adoption Framework (v0.12.0+)
-
-Phase 1 introduces features designed to make MemoryRelay "just work" without manual effort. The goal: store 3-5x more memories with zero additional work.
-
-### Smart Auto-Capture (Issue #12)
-
-**Tier-Based Privacy System** — Four capture modes with built-in privacy protection:
+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` | **Default** — Balanced automation | Medium (blocks sensitive data) |
+| `smart` | Balanced automation | Medium (blocks sensitive data) |
 | `aggressive` | Maximum capture | Low (minimal blocking) |
 
-**Privacy Blocklist** — Automatically filters:
-- Passwords and API keys (`password: xxx`, `api_key=xxx`)
-- Credit card numbers (Visa, MC, Amex, Discover patterns)
-- Social Security Numbers (`SSN: xxx-xx-xxxx`)
-- Email addresses and phone numbers (when tier < aggressive)
-
-**Configuration**:
+**Privacy Blocklist** — Automatically filters passwords, API keys, credit card numbers, SSNs, and other sensitive data.
 
 ```json
 {
@@ -108,270 +97,7 @@ Phase 1 introduces features designed to make MemoryRelay "just work" without man
 }
 ```
 
-**Backward Compatibility**: Boolean values still work (`true` → `{enabled: true, tier: "smart"}`)
-
-**First-5 Confirmations** — On `smart`/`aggressive` tiers, first 5 captures show confirmation prompts. After 5, auto-capture runs silently. Reset by setting `confirmFirst: 5` again.
-
----
-
-### Daily Memory Stats (Issue #10)
-
-**Morning Check** (9:00 AM) — Start your day with memory growth stats:
-```
-📊 Memory Stats (Morning Check)
-Total: 1,247 memories | Today: 8 (+3 since yesterday)
-This week: 52 memories (+15% vs last week)
-Top categories: development (18), decisions (12), patterns (7)
-```
-
-**Evening Review** (8:00 PM) — End your day with activity summary:
-```
-🌙 Memory Activity (Evening Review)  
-Today: 12 memories stored | Most recalled: "NorthRelay API v9.0 architecture"
-Most valuable: [Memory about critical bug fix in authentication flow]
-```
-
-**Gateway Method**: `memoryrelay:heartbeat`
-
-**Configuration**:
-```json
-{
-  "dailyStats": {
-    "enabled": true,
-    "morningTime": "09:00",
-    "eveningTime": "20:00"
-  }
-}
-```
-
-**Integration with HEARTBEAT.md** — Add to your workspace `HEARTBEAT.md`:
-```markdown
-## MemoryRelay Health
-Every heartbeat, check memory stats:
-- Run morning check at 9 AM
-- Run evening review at 8 PM
-- Report if memory storage rate drops below 5/week
-```
-
----
-
-### CLI Stats Command (Issue #11)
-
-**Comprehensive Statistics** — View memory metrics anytime:
-
-```bash
-openclaw gateway-call memoryrelay.stats
-```
-
-**Text Output**:
-```
-MemoryRelay Statistics
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Storage
-  Total: 1,247 memories
-  Today: 8 memories
-  This week: 52 memories (+15% vs last week)
-  This month: 218 memories (+8% vs last month)
-
-Top 10 Categories
-  development ........................ 342 (27%)
-  decisions .......................... 156 (12%)
-  patterns ........................... 128 (10%)
-  infrastructure ..................... 94 (8%)
-  [...]
-
-Recent Memories (last 5)
-  [2026-03-06 12:35] Phase 1 validation test
-  [2026-03-06 10:25] Phase 1 implementation complete
-  [2026-03-06 09:11] Issue #8 broken down
-  [...]
-```
-
-**JSON Output** (for scripts):
-```bash
-openclaw gateway-call memoryrelay.stats '{"format": "json"}'
-```
-
-**Verbose Mode** (includes growth charts, recall stats):
-```bash
-openclaw gateway-call memoryrelay.stats '{"verbose": true}'
-```
-
----
-
-### First-Run Onboarding (Issue #9)
-
-**Automatic Welcome** — On fresh install (no memories + no onboarding state):
-
-1. Plugin detects first run
-2. Creates welcome memory: "Welcome to MemoryRelay! This is your first memory."
-3. Shows auto-capture explanation
-4. Saves state to `~/.openclaw/memoryrelay-onboarding.json`
-5. Never repeats (state file persists)
-
-**Manual Trigger** (show again or for new users):
-```bash
-openclaw gateway-call memoryrelay.onboarding
-```
-
-**What Users See**:
-```
-🎉 Welcome to MemoryRelay!
-
-I just stored my first memory: "Welcome to MemoryRelay! This is your first memory."
-
-Auto-capture is enabled (tier: smart). I'll automatically remember:
-✓ Important decisions and changes
-✓ Technical discoveries and solutions  
-✓ Project context and conventions
-
-Privacy protected — I filter out:
-✗ Passwords and API keys
-✗ Credit card numbers
-✗ Social Security Numbers
-✗ Personal secrets
-
-You're all set! I'll build memory over time as we work together.
-```
-
----
-
-### Gateway Methods Summary
-
-| Method | Purpose | Example |
-|--------|---------|---------|
-| `memoryrelay:heartbeat` | Daily stats check (morning/evening) | `openclaw gateway-call memoryrelay.heartbeat` |
-| `memoryrelay:stats` | CLI stats command | `openclaw gateway-call memoryrelay.stats '{"format": "json"}'` |
-| `memoryrelay:onboarding` | Show/restart onboarding | `openclaw gateway-call memoryrelay.onboarding` |
-
-**Note**: These are gateway methods, not shell commands. Invoke via `openclaw gateway-call memoryrelay.<method>`.
-
----
-
-### Expected Impact
-
-Based on Zero-Friction Adoption Strategy (Issue #8):
-
-| Metric | Before | After Phase 1 | Target |
-|--------|--------|---------------|--------|
-| Memory storage rate | 5/week | 15-25/week | 3-5x |
-| Daily active usage | 10% | 40-50% | 4-5x |
-| Auto-capture adoption | 0% | 40-50% | 70% |
-| First memory time | N/A | <2 min | <5 min |
-
----
-
-## Debug & Monitoring (v0.8.0+)
-
-### Enable Debug Mode
-
-```json
-{
-  "plugins": {
-    "entries": {
-      "plugin-memoryrelay-ai": {
-        "enabled": true,
-        "config": {
-          "apiKey": "mem_prod_xxxxx",
-          "agentId": "your-agent",
-          "debug": true,
-          "verbose": false,
-          "maxLogEntries": 1000
-        }
-      }
-    }
-  }
-}
-```
-
-### Debug Commands (Gateway Methods)
-
-The plugin provides four debug commands accessible via OpenClaw gateway methods:
-
-**Note**: These are **gateway methods**, not standalone shell commands. Invoke them using `openclaw gateway-call memoryrelay.<method>`.
-
-#### View Debug Logs
-```bash
-# Last 20 logs
-openclaw gateway-call memoryrelay.logs
-
-# Last 50 logs
-openclaw gateway-call memoryrelay.logs '{"limit": 50}'
-
-# Filter by tool
-openclaw gateway-call memoryrelay.logs '{"tool": "memory_store", "limit": 20}'
-
-# Show errors only
-openclaw gateway-call memoryrelay.logs '{"errorsOnly": true}'
-```
-
-#### Health Check
-```bash
-# Run comprehensive health check
-openclaw gateway-call memoryrelay.health
-
-# Tests API connectivity, authentication, and core tools
-```
-
-#### Test Individual Tools
-```bash
-# Test specific tool
-openclaw gateway-call memoryrelay.test '{"tool": "memory_store"}'
-openclaw gateway-call memoryrelay.test '{"tool": "memory_recall"}'
-openclaw gateway-call memoryrelay.test '{"tool": "project_list"}'
-```
-
-#### View Performance Metrics
-```bash
-# Show performance statistics
-openclaw gateway-call memoryrelay.metrics
-
-# Displays per-tool metrics:
-# - Call count
-# - Success rate
-# - Average duration
-# - p95/p99 latencies
-```
-
-### Alternative: Direct Gateway Method Calls
-
-The same methods can be called programmatically from code or scripts (same syntax as above).
-
-### Enhanced Status Reporting
-
-The `memory.status` gateway method now provides comprehensive reports including:
-
-- Connection status with response time
-- Tool breakdown by category (39 tools across 8 groups)
-- Recent API call history
-- Known issues with affected tools
-- Debug/verbose mode status
-
-```bash
-openclaw gateway call memory.status
-```
-
-### Debug Log Format
-
-When debug mode is enabled, each API call is logged with:
-
-```
-TIMESTAMP          TOOL                    DURATION  STATUS  ERROR
-━━━━━━━━━━━━━━━━━  ━━━━━━━━━━━━━━━━━━━━━  ━━━━━━━━  ━━━━━━  ━━━━━━━━━━━━━━━━━━━
-7:35:15 PM        memory_store              142ms  ✓      
-7:35:10 PM        memory_recall              78ms  ✓      
-7:35:05 PM        memory_batch_store        245ms  ✗      500 Internal Server Error
-```
-
-Verbose mode additionally captures request/response bodies for deep troubleshooting.
-
-### Performance Impact
-
-- **Debug disabled**: ~0ms overhead (no-op checks)
-- **Debug enabled**: ~1-2ms per call (logging only)
-- **Verbose enabled**: ~2-5ms per call (includes JSON serialization)
-- **Memory usage**: ~10KB (default 100 entries) to ~100KB (1000 entries)
+With `confirmFirst`, the first N captures show confirmation prompts before running silently.
 
 ## Agent Workflow
 
@@ -509,33 +235,48 @@ Exclude specific channels from auto-recall and workflow injection:
 }
 ```
 
-## CLI Commands
+## Debug & Monitoring
 
-```bash
-openclaw memoryrelay status   # Check connection and stats
-openclaw memoryrelay stats    # Show memory count
-openclaw memoryrelay list     # List recent memories
-openclaw memoryrelay search "query"  # Search memories
-openclaw memoryrelay delete <id>     # Delete a memory
-openclaw memoryrelay export          # Export all memories to JSON
+### Enable Debug Mode
+
+```json
+{
+  "debug": true,
+  "verbose": false,
+  "maxLogEntries": 1000
+}
 ```
 
+### Gateway Methods
+
+| 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` |
+
+### Debug Log Format
+
+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.
+
 ## Privacy & Security
 
 - **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
-- **No Auto-Capture by Default** — Manual storage gives you full control
-- **Never store secrets** — Do not store API keys, passwords, or tokens as memories. Use encrypted local files or secret managers instead.
+- **Privacy Blocklist** — Auto-capture filters sensitive data (passwords, SSNs, credit cards, API keys)
+- **Never store secrets** — Do not store API keys, passwords, or tokens as memories
 
 ## Troubleshooting
 
 ### Plugin Not Loading
 
-**Symptoms**: Plugin doesn't appear in `openclaw plugins list` or shows as "unavailable"
-
-**Solutions**:
 ```bash
 # Check if installed
 npm list -g @memoryrelay/plugin-memoryrelay-ai
@@ -543,9 +284,6 @@ npm list -g @memoryrelay/plugin-memoryrelay-ai
 # Reinstall if needed
 openclaw plugins install @memoryrelay/plugin-memoryrelay-ai --force
 
-# Check config syntax
-cat ~/.openclaw/openclaw.json | jq '.plugins.entries."plugin-memoryrelay-ai"'
-
 # Restart gateway
 openclaw gateway restart
 
@@ -555,265 +293,25 @@ openclaw gateway logs | grep memoryrelay
 
 ### API Connection Issues
 
-**Symptoms**: "Failed to connect" errors, timeouts, or "unhealthy" status
-
-**Solutions**:
 ```bash
 # Test API directly
 curl -H "X-API-Key: YOUR_KEY" https://api.memoryrelay.net/v1/health
 
 # Check gateway logs
 openclaw gateway logs -f | grep memory-memoryrelay
-
-# Verify API key format (should be mem_prod_xxxxx with 32 chars after prefix)
-openclaw config get plugins.entries.plugin-memoryrelay-ai.config.apiKey
-
-# Run health check
-memoryrelay-health
 ```
 
 ### Auto-Recall Not Working
 
-**Symptoms**: Memories not appearing in agent context
-
-**Checks**:
 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. Review logs: `openclaw gateway logs | grep "injecting.*memories"`
-5. Check channel not in `excludeChannels`
-
-### Debug Mode Not Working
-
-**Symptoms**: `memoryrelay-logs` shows "No logs" or debug commands fail
-
-**Solutions**:
-1. Verify `debug: true` in config
-2. Restart gateway after config change: `openclaw gateway restart`
-3. Use the plugin to generate logs
-4. Check `maxLogEntries` isn't set too low (default: 100)
-
-### Tool Not Found Errors
-
-**Symptoms**: "Tool xxx not found" or "Tool not enabled"
-
-**Solutions**:
-1. Check `enabledTools` config (should be `"all"` or include the tool's group)
-2. Verify tool name spelling matches exactly (e.g., `memory_store` not `memoryStore`)
-3. Check plugin version: `npm list -g @memoryrelay/plugin-memoryrelay-ai`
-4. Update to latest: `openclaw plugins install @memoryrelay/plugin-memoryrelay-ai@latest`
-
-### Performance Issues
-
-**Symptoms**: Slow API calls, timeouts, high latency
-
-**Diagnosis**:
-```bash
-# Enable debug mode
-openclaw config set plugins.entries.plugin-memoryrelay-ai.config.debug true
-openclaw gateway restart
-
-# View metrics
-memoryrelay-metrics
-
-# Check for slow tools (high avgDuration or p99)
-# Check for failures (low successRate)
-```
-
-**Solutions**:
-1. Check network latency to api.memoryrelay.net
-2. Reduce `recallLimit` (fewer memories = faster)
-3. Lower `recallThreshold` (fewer vector comparisons)
-4. Check MemoryRelay API status at status.memoryrelay.ai
-
-### Memory Storage Failures
-
-**Symptoms**: `memory_store` returns 422 validation errors or 500 errors
-
-**Common Causes**:
-1. Content too long (max 50,000 characters)
-2. Metadata too large (max 10KB when serialized)
-3. Invalid project slug (use `project_list` to verify)
-4. API rate limits exceeded (30 req/min for memory_store)
-
-**Solutions**:
-```bash
-# Test with minimal memory
-openclaw gateway call memory_store '{"content": "Test memory"}'
-
-# Check recent errors
-memoryrelay-logs --errors-only --limit=10
-
-# Verify API key has write permissions
-curl -X POST https://api.memoryrelay.net/v1/memories \
-  -H "X-API-Key: YOUR_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{"content": "Test"}'
-```
-
-### Session Tracking Issues
-
-**Symptoms**: `session_start` fails or `session_end` can't find session
-
-**Solutions**:
-1. Save session ID from `session_start` response
-2. Verify project exists: `openclaw gateway call project_list`
-3. Check for API validation errors in logs
-4. Use `session_list` to find active sessions
+4. Check channel not in `excludeChannels`
 
 ### Known Limitations
 
-**API Issues** (reported to MemoryRelay team):
 - `memory_batch_store`: May return 500 errors (use individual `memory_store` as workaround)
 - `memory_context`: Returns 405 Method Not Allowed (use `memory_recall` instead)
-- `entity_create`: May fail with 422 validation errors
-- `decision_record`: May fail with 422 validation errors
-- `session_start`: May fail with 422 validation errors
-
-**Workarounds**:
-- Use alternative tools where available
-- Check GitHub Issues for latest status
-- Enable debug mode to capture full error details
-
-## Changelog
-
-### v0.12.7 (2026-03-06)
-
-**🎯 Tool Factory Pattern Fix - Session Tracking Now Works!**
-
-- **FIX**: Converted all 39 tools from direct registration to factory pattern for context access
-- **FIX**: Session tracking now works - `ctx.sessionId` properly captured via factory closure
-- **CHANGE**: Tools now registered via `api.registerTool((ctx) => tool)` instead of direct objects
-- **CHANGE**: Removed unused `context?` parameter from execute functions
-- **ROOT CAUSE**: OpenClaw passes context to tool factories at registration time, NOT to execute functions
-- **EVIDENCE**: Examined OpenClaw core source code (`src/plugins/types.ts`, `OpenClawPluginToolFactory`)
-- **AUTOMATION**: Python script converted all 39 tools automatically
-- **IMPACT**: Session-memory linking finally works end-to-end
-- **BACKWARD COMPAT**: Fully compatible, no breaking changes, graceful degradation
-- **RELATED**: Closes #26, part of session tracking fix chain (#24, #25, #226)
-
-**Files changed**: 7 files, 5,176 insertions(+), 246 deletions(-)  
-**Implementation time**: 1.5 hours  
-**Total investigation**: ~7 hours across 6 sessions
-
-### v0.12.6 (2026-03-06)
-
-**⚠️ Wrong Approach - Superseded by v0.12.7**
-
-- **ATTEMPT**: Added context parameter to execute functions
-- **ISSUE**: OpenClaw doesn't pass context to execute - wrong pattern
-- **LESSON**: Should have checked OpenClaw source code first
-
-### v0.12.5 (2026-03-06)
-
-**🔧 Version String Sync**
-
-- **FIX**: Synchronized all version strings across package.json, openclaw.plugin.json, and index.ts
-- **IMPACT**: Gateway now displays correct version (v0.12.5)
-
-### v0.12.4 (2026-03-06)
-
-**❌ Failed Release**
-
-- **ISSUE**: Created git tag before pushing version bump commit
-- **RESULT**: Published to npm without version string updates
-- **LESSON**: Always push commits before tagging releases
-
-### v0.12.3 (2026-03-06)
-
-**🔗 Session Tracking - Plugin Fix**
-
-- **FIX**: Extract session_id from metadata and pass as top-level parameter to API
-- **CHANGE**: Backend expects `{ session_id, content, metadata }`, not `{ content, metadata: { session_id } }`
-- **IMPACT**: Memories now correctly link to sessions in database
-- **RELATED**: Backend fixed in PR #225, plugin integration fixed here
-
-### v0.12.2 (2026-03-06)
-
-**📚 Documentation & Maintenance Release**
-
-- **FIX**: Corrected Node.js requirement from >=18.0.0 to >=20.0.0 (CI uses Node 20, dependencies require 20+)
-- **FIX**: Version string in plugin load message now shows correct version (was hardcoded to 0.12.0)
-- **DOCS**: Complete Phase 1 features documentation added
-- **DOCS**: Updated `autoCapture` configuration with tier system details
-- **DOCS**: Added v0.12.0 and v0.12.1 changelog entries (were missing)
-- **DOCS**: Clarified gateway methods vs CLI commands
-- **DOCS**: Added troubleshooting for Phase 1 features
-
-### v0.12.1 (2026-03-06)
-
-**🐛 Bugfix Release**
-
-- **FIX**: Include `src/` directory in npm package (Phase 1 modules were missing)
-- **FIX**: Package.json `files` array now includes `src/` for heartbeat, cli, and onboarding modules
-- **IMPACT**: Critical fix - v0.12.0 was non-functional without src/ directory
-
-### v0.12.0 (2026-03-06)
-
-**🎉 Phase 1: Zero-Friction Adoption Framework**
-
-- **NEW**: Smart auto-capture with 4 privacy tiers (off/conservative/smart/aggressive)
-- **NEW**: Privacy blocklist for sensitive data (passwords, SSN, credit cards, API keys)
-- **NEW**: Daily memory stats in heartbeat (morning 9 AM, evening 8 PM)
-- **NEW**: CLI stats command with text/JSON output (`memoryrelay:stats`)
-- **NEW**: First-run onboarding wizard with welcome memory
-- **NEW**: Three gateway methods: `memoryrelay:heartbeat`, `memoryrelay:stats`, `memoryrelay:onboarding`
-- **NEW**: Auto-capture default changed from `false` to `smart` tier
-- **NEW**: Modular architecture with `src/` directory (heartbeat, cli, onboarding modules)
-- **CHANGE**: `autoCapture` config accepts boolean (backward compat) or object with tier system
-- **DOCS**: PHASE1_CHANGELOG.md with complete implementation details
-- **TESTS**: All existing tests pass, Phase 1 features validated
-
-**Implementation**: 820 lines across 3 new modules  
-**Time**: 50 minutes (38% faster than 80-minute estimate)  
-**Backward Compatibility**: Fully compatible, no breaking changes
-
-### v0.8.0 (2026-03-05)
-
-**🚀 Debug & Monitoring Release**
-
-- **NEW**: Debug logging system with circular buffer (configurable maxLogEntries)
-- **NEW**: DebugLogger class tracks all API calls with timing, status, errors
-- **NEW**: StatusReporter class provides enhanced status reports
-- **NEW**: 4 CLI commands: `memoryrelay-logs`, `memoryrelay-health`, `memoryrelay-test`, `memoryrelay-metrics`
-- **NEW**: 4 gateway methods: `memoryrelay.logs`, `memoryrelay.health`, `memoryrelay.test`, `memoryrelay.metrics`
-- **NEW**: Performance metrics with p95/p99 latency tracking
-- **NEW**: Enhanced `memory.status` handler with comprehensive reports
-- **NEW**: Debug config options: `debug`, `verbose`, `logFile`, `maxLogEntries`
-- **NEW**: Tool failure tracking and recovery monitoring
-- **NEW**: Request/response capture in verbose mode
-- **NEW**: Persistent file logging option
-- **TESTS**: 92 tests total (73 existing + 19 new for DebugLogger and StatusReporter)
-- **DOCS**: CLI_COMMANDS.md with complete usage guide
-- **DOCS**: Enhanced README with Debug & Monitoring section
-- **DOCS**: Comprehensive troubleshooting guide
-
-**Performance**: Minimal overhead when disabled (~0ms), 1-2ms when enabled, 2-5ms in verbose mode
-
-### v0.7.0 (2026-03-05)
-
-- **NEW**: 39 tools (up from 3) covering full MemoryRelay API surface
-- **NEW**: Session tracking — `session_start`, `session_end`, `session_recall`, `session_list`
-- **NEW**: Decision records — `decision_record`, `decision_list`, `decision_supersede`, `decision_check`
-- **NEW**: Pattern library — `pattern_create`, `pattern_search`, `pattern_adopt`, `pattern_suggest`
-- **NEW**: Project management — `project_register`, `project_list`, `project_info`, relationships, impact analysis, shared patterns, full context loading
-- **NEW**: Enhanced memory tools — project scoping, deduplication, importance scores, three-tier storage, batch store, context building, promotion
-- **NEW**: Agent workflow instructions injected via `before_agent_start` hook
-- **NEW**: Tool group filtering via `enabledTools` config
-- **NEW**: `defaultProject` config for automatic project scoping
-- **FIX**: Workflow instructions now injected regardless of autoRecall setting
-
-### v0.6.2 (2026-03-01)
-
-- **FIX**: OpenClaw 2026.2.26 compatibility — Changed `extensions` from `["./"]` to `["./index.ts"]`
-- **DOCS**: Added comprehensive README and migration guide
-
-### v0.6.0 (2026-02-18)
-
-- **NEW**: Retry logic with exponential backoff (3 attempts)
-- **NEW**: Request timeout (30 seconds)
-- **NEW**: Environment variable fallback support
-- **NEW**: Channel filtering (`excludeChannels` config)
 
 ## Development
 
@@ -821,9 +319,9 @@ curl -X POST https://api.memoryrelay.net/v1/memories \
 git clone https://github.com/memoryrelay/openclaw-plugin.git
 cd openclaw-plugin
 npm install
-npm test              # Run once (50 tests)
-npm run test:watch    # Watch mode
-npm run test:coverage # With coverage
+npm test
+npm run test:watch
+npm run test:coverage
 ```
 
 ## License

package/index.ts

@@ -974,6 +974,22 @@ class MemoryRelayClient {
     });
   }
 
+  async getOrCreateSession(
+    external_id: string,
+    agent_id?: string,
+    title?: string,
+    project?: string,
+    metadata?: Record<string, string>,
+  ): Promise<any> {
+    return this.request("POST", "/v1/sessions/get-or-create", {
+      external_id,
+      agent_id: agent_id || this.agentId,
+      title,
+      project,
+      metadata,
+    });
+  }
+
   async endSession(id: string, summary?: string): Promise<any> {
     return this.request("PUT", `/v1/sessions/${id}/end`, { summary });
   }
@@ -1316,6 +1332,78 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
   
   const client = new MemoryRelayClient(apiKey, agentId, apiUrl, debugLogger, statusReporter);
 
+  // ========================================================================
+  // Session Cache for External Session IDs (v0.12.11)
+  // ========================================================================
+  
+  /**
+   * Cache mapping: external_id → MemoryRelay session_id
+   * Enables multi-agent collaboration and conversation-spanning sessions
+   */
+  const sessionCache = new Map<string, string>();
+  
+  /**
+   * Get or create MemoryRelay session for current workspace/project context.
+   * Uses external_id as semantic key for multi-agent collaboration.
+   * 
+   * @param project - Project slug (from context or user args)
+   * @param workspaceDir - Workspace directory path
+   * @returns MemoryRelay session UUID, or null if session creation disabled
+   */
+  async function getContextSession(
+    project?: string,
+    workspaceDir?: string
+  ): Promise<string | null> {
+    // If no project context, don't auto-create session
+    if (!project && !workspaceDir) {
+      return null;
+    }
+    
+    // Generate external_id from project or workspace
+    const externalId = project ||
+      (workspaceDir ? `workspace-${workspaceDir.split(/[/\\]/).pop()}` : null);
+    
+    if (!externalId) {
+      return null;
+    }
+    
+    // Check cache first
+    if (sessionCache.has(externalId)) {
+      if (debugLogger) {
+        debugLogger.log(`Session: Cache hit for external_id="${externalId}"`, "info");
+      }
+      return sessionCache.get(externalId)!;
+    }
+    
+    try {
+      // Get or create session via new API endpoint
+      const response = await client.getOrCreateSession(
+        externalId,
+        agentId,
+        project ? `${project} work session` : `Workspace ${externalId}`,
+        project,
+        { source: "openclaw-plugin", agent: agentId }
+      );
+      
+      // Cache the mapping
+      sessionCache.set(externalId, response.id);
+      
+      if (debugLogger) {
+        debugLogger.log(
+          `Session: ${response.created ? 'Created' : 'Retrieved'} session ${response.id} for external_id="${externalId}"`,
+          "info"
+        );
+      }
+      
+      return response.id;
+    } catch (err) {
+      if (debugLogger) {
+        debugLogger.log(`Session: Failed to get-or-create session for ${externalId}: ${String(err)}`, "error");
+      }
+      return null;
+    }
+  }
+
   // Verify connection on startup (with timeout)
   try {
     await client.health();
@@ -1523,6 +1611,10 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
               description: "Memory tier: hot, warm, or cold.",
               enum: ["hot", "warm", "cold"],
             },
+            session_id: {
+              type: "string",
+              description: "Optional MemoryRelay session UUID to associate this memory with. If omitted and project is set, plugin auto-creates session via external_id.",
+            },
           },
           required: ["content"],
         },
@@ -1536,27 +1628,41 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
             project?: string;
             importance?: number;
             tier?: string;
+            session_id?: string;  // Allow explicit session_id
           },
         ) => {
           try {
-            const { content, metadata, ...opts } = args;
+            const { content, metadata, session_id: explicitSessionId, ...opts } = args;
+            
+            // Apply defaultProject fallback before session resolution
+            if (!opts.project && defaultProject) opts.project = defaultProject;
+
+            // Get session_id from cache if project context available
+            // Priority: explicit session_id > context session > no session
+            let sessionId: string | undefined = explicitSessionId;
+
+            if (!sessionId && (opts.project || ctx.workspaceDir)) {
+              const contextSessionId = await getContextSession(opts.project, ctx.workspaceDir);
+              if (contextSessionId) {
+                sessionId = contextSessionId;
+              }
+            }
             
-            // Inject sessionId from OpenClaw context into metadata
-            const enrichedMetadata = {
-              ...metadata,
-              ...(ctx.sessionId && { session_id: ctx.sessionId }),
+            // Build request options with session_id as top-level parameter
+            const storeOpts = {
+              ...opts,
+              ...(sessionId && { session_id: sessionId }),
             };
             
-            if (!opts.project && defaultProject) opts.project = defaultProject;
-            const memory = await client.store(content, enrichedMetadata, opts);
+            const memory = await client.store(content, metadata, storeOpts);
             return {
               content: [
                 {
                   type: "text",
-                  text: `Memory stored successfully (id: ${memory.id.slice(0, 8)}...)`,
+                  text: `Memory stored successfully (id: ${memory.id.slice(0, 8)}...)${sessionId ? ` in session ${sessionId.slice(0, 8)}...` : ''}`,
                 },
               ],
-              details: { id: memory.id, stored: true },
+              details: { id: memory.id, stored: true, session_id: sessionId },
             };
           } catch (err) {
             return {
@@ -3864,7 +3970,7 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
   }
 
   api.logger.info?.(
-    `memory-memoryrelay: plugin v0.12.8 loaded (39 tools, autoRecall: ${cfg?.autoRecall}, autoCapture: ${autoCaptureConfig.enabled ? autoCaptureConfig.tier : 'off'}, debug: ${debugEnabled})`,
+    `memory-memoryrelay: plugin v0.12.11 loaded (39 tools, autoRecall: ${cfg?.autoRecall}, autoCapture: ${autoCaptureConfig.enabled ? autoCaptureConfig.tier : 'off'}, debug: ${debugEnabled})`,
   );
 
   // ========================================================================

package/openclaw.plugin.json

@@ -2,8 +2,8 @@
   "id": "plugin-memoryrelay-ai",
   "kind": "memory",
   "name": "MemoryRelay AI",
-  "description": "MemoryRelay v0.12.6 - Long-term memory with sessions, decisions, patterns & projects (api.memoryrelay.net)",
-  "version": "0.12.9",
+  "description": "MemoryRelay v0.12.11 - Long-term memory with sessions, decisions, patterns & projects (api.memoryrelay.net)",
+  "version": "0.12.11",
   "uiHints": {
     "apiKey": {
       "label": "MemoryRelay API Key",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memoryrelay/plugin-memoryrelay-ai",
-  "version": "0.12.9",
+  "version": "0.12.11",
   "description": "OpenClaw memory plugin for MemoryRelay API - sessions, decisions, patterns, projects & semantic search",
   "type": "module",
   "main": "index.ts",