@memoryrelay/plugin-memoryrelay-ai 0.12.10 → 0.13.0

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.10",
+  "description": "MemoryRelay v0.13.0 - Long-term memory with sessions, decisions, patterns & projects (api.memoryrelay.net)",
+  "version": "0.13.0",
   "uiHints": {
     "apiKey": {
       "label": "MemoryRelay API Key",
@@ -45,6 +45,18 @@
       "label": "Exclude Channels",
       "help": "List of channel IDs to skip auto-recall (e.g., ['whatsapp:group_123', 'telegram:456'])",
       "advanced": true
+    },
+    "sessionTimeoutMinutes": {
+      "label": "Session Timeout (minutes)",
+      "placeholder": "120",
+      "advanced": true,
+      "help": "Auto-close MemoryRelay sessions inactive for this many minutes (default: 120)"
+    },
+    "sessionCleanupIntervalMinutes": {
+      "label": "Cleanup Interval (minutes)",
+      "placeholder": "30",
+      "advanced": true,
+      "help": "How often to check for stale sessions (default: 30)"
     }
   },
   "configSchema": {
@@ -101,6 +113,20 @@
         "default": [],
         "description": "List of channel IDs to exclude from auto-recall"
       },
+      "sessionTimeoutMinutes": {
+        "type": "number",
+        "default": 120,
+        "minimum": 10,
+        "maximum": 1440,
+        "description": "Auto-close sessions inactive for this many minutes"
+      },
+      "sessionCleanupIntervalMinutes": {
+        "type": "number",
+        "default": 30,
+        "minimum": 5,
+        "maximum": 360,
+        "description": "How often to check for stale sessions (minutes)"
+      },
       "debug": {
         "type": "boolean",
         "default": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memoryrelay/plugin-memoryrelay-ai",
-  "version": "0.12.10",
+  "version": "0.13.0",
   "description": "OpenClaw memory plugin for MemoryRelay API - sessions, decisions, patterns, projects & semantic search",
   "type": "module",
   "main": "index.ts",
@@ -48,7 +48,8 @@
     "openclaw.plugin.json",
     "README.md",
     "LICENSE",
-    "src/"
+    "src/",
+    "skills/"
   ],
   "engines": {
     "node": ">=20.0.0"

package/skills/codebase-navigation/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: codebase-navigation
+description: "Use when navigating the openclaw-plugin codebase for the first time, looking for where a tool is registered, understanding the monolithic index.ts structure, or adding a new tool or hook."
+---
+
+# Codebase Navigation
+
+The plugin is a single monolithic `index.ts` (4839 lines) plus a few extracted modules.
+
+## index.ts File Map
+
+| Lines | Section |
+|-------|---------|
+| 1--14 | Header comments and version info |
+| 16--36 | Imports (plugin SDK, heartbeat, CLI stats, onboarding) |
+| 38--47 | Constants (`DEFAULT_API_URL`, `REQUEST_TIMEOUT_MS`, `MAX_RETRIES`) |
+| 48--121 | `DebugLogger` class (inlined) with `LogEntry`, `DebugLoggerConfig` |
+| 123--404 | `StatusReporter` class (inlined) with `ToolStatus`, `ConnectionStatus`, `MemoryStats` |
+| 406--461 | Types: `AutoCaptureConfig`, `MemoryRelayConfig`, `Memory`, `SearchResult`, `Stats` |
+| 463--648 | Utility functions: `sleep`, `isRetryableError`, `fetchWithTimeout`, auto-capture helpers, `redactSensitive`, `extractRescueContent` |
+| 650--1294 | `MemoryRelayClient` class (API client with retry logic, all endpoints) |
+| 1296--1315 | Pattern detection for auto-capture (`CAPTURE_PATTERNS`, `shouldCapture`) |
+| 1317--1562 | Plugin entry: `export default async function plugin(api)`, config resolution, client init, session cache, `touchSession` |
+| 1564--1613 | `TOOL_GROUPS` map and `isToolEnabled()` |
+| 1615--3747 | 39 tool registrations |
+| 3749--3853 | CLI commands (`memoryrelay status/stats/list/export`) |
+| 3855--4240 | 14 lifecycle hooks (`before_agent_start`, `agent_end`, `session_start`, `session_end`, `before_tool_call`, `after_tool_call`, `before_compaction`, `before_reset`, `message_received`, `message_sending`, `before_message_write`, `subagent_spawned`, `subagent_ended`, `tool_result_persist`) |
+| 4242--4274 | First-run onboarding |
+| 4276--4586 | Gateway methods (`memoryrelay.logs`, `.health`, `.metrics`, `.heartbeat`, `.onboarding`, `.stats`, `.test`) |
+| 4588--4790 | Direct commands: `/memory-status`, `/memory-stats`, `/memory-health`, `/memory-logs`, `/memory-metrics` |
+| 4792--4839 | Stale session cleanup service (`memoryrelay-session-cleanup` via `api.registerService`) |
+
+## Tool Registration Pattern
+
+Every tool follows this pattern:
+
+```typescript
+if (isToolEnabled("tool_name")) {
+  api.registerTool((ctx) => ({
+    name: "tool_name",
+    description: "...",
+    parameters: { /* JSON schema */ },
+    execute: async (_id, args) => { /* impl */ }
+  }), { name: "tool_name" });
+}
+```
+
+Tools are numbered 1--39 with comment markers (e.g., `// 1. memory_store`). Search for `// N.` to jump to a specific tool.
+
+## TOOL_GROUPS (line 1569)
+
+| Group | Count | Tools |
+|-------|-------|-------|
+| memory | 9 | `memory_store`, `memory_recall`, `memory_forget`, `memory_list`, `memory_get`, `memory_update`, `memory_batch_store`, `memory_context`, `memory_promote` |
+| entity | 4 | `entity_create`, `entity_link`, `entity_list`, `entity_graph` |
+| agent | 3 | `agent_list`, `agent_create`, `agent_get` |
+| session | 4 | `session_start`, `session_end`, `session_recall`, `session_list` |
+| decision | 4 | `decision_record`, `decision_list`, `decision_supersede`, `decision_check` |
+| pattern | 4 | `pattern_create`, `pattern_search`, `pattern_adopt`, `pattern_suggest` |
+| project | 10 | `project_register`, `project_list`, `project_info`, `project_add_relationship`, `project_dependencies`, `project_dependents`, `project_related`, `project_impact`, `project_shared_patterns`, `project_context` |
+| health | 1 | `memory_health` |
+
+The `enabledTools` config option accepts a comma-separated list of group names (or `"all"`).
+
+## Supporting Modules
+
+| File | Purpose |
+|------|---------|
+| `src/debug-logger.ts` | `DebugLogger` class (source of the inlined copy) |
+| `src/status-reporter.ts` | `StatusReporter` class (source of the inlined copy) |
+| `src/heartbeat/daily-stats.ts` | Morning/evening summaries, `calculateStats`, `formatStatsForDisplay` |
+| `src/onboarding/first-run.ts` | Onboarding wizard: `checkFirstRun`, `runSimpleOnboarding` |
+| `src/cli/stats-command.ts` | CLI `stats` command handler |
+
+## Configuration Fallback Chain
+
+```
+Plugin config (openclaw.json) -> Env vars -> Defaults
+```
+
+- `apiKey`: `cfg.apiKey` -> `MEMORYRELAY_API_KEY` (required, no default)
+- `agentId`: `cfg.agentId` -> `MEMORYRELAY_AGENT_ID` -> `api.agentName`
+- `apiUrl`: `cfg.apiUrl` -> `MEMORYRELAY_API_URL` -> `https://api.memoryrelay.net`
+
+## Key Types
+
+| Type | Location | Purpose |
+|------|----------|---------|
+| `Memory` | L442 | Core memory record (`id`, `content`, `agent_id`, `metadata`, `entities`) |
+| `SearchResult` | L453 | Vector search hit (`memory`, `score`) |
+| `Stats` | L458 | Agent statistics (`total_memories`, `last_updated`) |
+| `LogEntry` | L52 | Debug log entry (tool, method, path, duration, status) |
+| `DebugLoggerConfig` | L66 | Logger settings (enabled, verbose, maxEntries) |
+| `ConnectionStatus` | L140 | API connection state (status, endpoint, responseTime) |
+| `ToolStatus` | L127 | Per-group tool health (enabled, available, failed) |
+
+## Key Helpers
+
+| Function | Location | Purpose |
+|----------|----------|---------|
+| `redactSensitive` | L591 | Replace blocklist patterns with `[REDACTED]` |
+| `extractRescueContent` | L608 | Salvage assistant messages before compaction/reset |
+| `touchSession` | L1444 | Update `lastActivityAt` timestamp in session cache |
+| `isToolEnabled` | L1605 | Check if a tool's group is in the enabled set |
+| `shouldCapture` | L1310 | Test text against `CAPTURE_PATTERNS` for auto-capture |

package/skills/decision-tracking/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: decision-tracking
+description: "Use when making architectural choices, evaluating alternatives, revisiting past decisions, or needing to check whether a decision already exists before committing to a direction."
+---
+
+# Decision Tracking
+
+Decisions are **choices with rationale and alternatives considered**. Plain facts, findings, or information are memories — use `memory_store` for those.
+
+## Decision Tools
+
+| Tool | Signature | Purpose |
+|------|-----------|---------|
+| `decision_record` | `decision_record(title, rationale, project)` | Record a new decision with reasoning |
+| `decision_list` | `decision_list(project)` | List all decisions for a project |
+| `decision_supersede` | `decision_supersede(old_id, new_title, new_rationale)` | Replace an outdated decision |
+| `decision_check` | `decision_check(query, project)` | Check for conflicting decisions before choosing |
+
+## Workflow
+
+1. **Check first** — Always call `decision_check(query, project)` before making an architectural choice. This surfaces existing decisions that may conflict or already cover the topic.
+2. **Record with rationale** — Use `decision_record(title, rationale, project)`. The rationale should include why this option was chosen and what alternatives were rejected.
+3. **Supersede, don't duplicate** — When a decision changes, call `decision_supersede(old_id, new_title, new_rationale)`. This preserves history while marking the old decision as replaced.
+4. **Review periodically** — Use `decision_list(project)` to audit active decisions during planning or refactoring.
+
+## Project Scoping
+
+Decisions must be scoped to the relevant project:
+
+- Set `defaultProject` in plugin config to avoid passing `project` on every call.
+- Pass `project` explicitly when working across multiple projects.
+- Unscoped decisions pollute search results and create false conflicts.
+
+## Decisions vs Memories
+
+| Store as Decision | Store as Memory |
+|-------------------|-----------------|
+| "Use PostgreSQL over MongoDB for user data" | "PostgreSQL supports JSONB columns" |
+| "Adopt ESM modules, drop CommonJS" | "Node 20 supports ESM natively" |
+| "API versioning via URL path, not headers" | "Team prefers REST over GraphQL" |
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Recording decisions with `memory_store` | Use `decision_record` — decisions need rationale tracking and conflict detection |
+| Making choices without `decision_check` | Always check first; conflicting decisions cause inconsistent architecture |
+| Adding a new decision when one already exists | Use `decision_supersede` to replace the old decision, preserving history |
+| Omitting the `project` parameter | Scope every decision to a project via parameter or `defaultProject` config |
+| Storing facts as decisions | Only choices with rationale belong in decisions; use `memory_store` for information |

package/skills/entity-and-context/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: entity-and-context
+description: "Use when building relationship maps between people, systems, services, or concepts that appear across multiple memories, or when recalling information that benefits from entity connections rather than flat search."
+---
+
+# Entity and Context
+
+Entities turn flat memory storage into a connected knowledge graph. Create entities for **named things that recur across multiple memories** and benefit from relationship tracking.
+
+## Relevant Tools
+
+| Tool | Signature | Purpose |
+|------|-----------|---------|
+| `entity_create` | `entity_create(name, type, description)` | Create a new entity node |
+| `entity_link` | `entity_link(entity_id, memory_id)` | Connect an entity to a memory |
+| `entity_list` | `entity_list(type?)` | List entities, optionally filtered by type |
+| `entity_graph` | `entity_graph(entity_id)` | Visualize an entity's relationships |
+| `memory_context` | `memory_context(query)` | Enriched recall with entity connections (memory group tool) |
+
+## Entity Types
+
+| Type | Examples |
+|------|----------|
+| `people` | Team members, stakeholders, external contacts |
+| `systems` | Databases, cloud platforms, internal tools |
+| `services` | APIs, microservices, third-party integrations |
+| `concepts` | Architecture patterns, business domains, protocols |
+| `teams` | Engineering squads, departments, working groups |
+| `repositories` | Codebases, monorepos, package libraries |
+
+## When to Create Entities
+
+Create an entity when a named thing:
+- Appears in **2+ memories** (not one-off mentions)
+- Has relationships worth tracking (owns, depends on, maintains)
+- Would benefit from graph traversal during recall
+
+## Linking Workflow
+
+1. **Create the entity** — `entity_create("AuthService", "services", "Handles OAuth2 and JWT token management")`
+2. **Store related memories** — `memory_store(content, metadata)` as usual
+3. **Link them** — `entity_link(entity_id, memory_id)` to connect entity to each relevant memory
+4. **Query with context** — `memory_context("authentication flow")` returns memories enriched with linked entity data
+5. **Explore connections** — `entity_graph(entity_id)` to see all related memories and co-linked entities
+
+## memory_context vs memory_recall
+
+| Use `memory_recall` | Use `memory_context` |
+|---------------------|----------------------|
+| Simple keyword/semantic search | Need entity relationships in results |
+| No entities involved | Entities are linked to relevant memories |
+| Quick lookup of isolated facts | Understanding how things connect |
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Creating entities for one-off mentions | Only create entities for things referenced across multiple memories |
+| Not linking entities to memories | An unlinked entity is invisible to `memory_context`; always link after creating |
+| Using `memory_recall` when entities exist | Switch to `memory_context` for richer results that include entity connections |
+| Creating duplicate entities | Call `entity_list(type)` first to check if the entity already exists |
+| Linking everything to one entity | Keep links specific; an entity should connect only to directly relevant memories |

package/skills/memory-workflow/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: memory-workflow
+description: "Use when starting a new conversation or task that needs persistent memory, storing or retrieving information across sessions, or working within a project that uses MemoryRelay."
+---
+
+# Memory Workflow
+
+Follow this order every time. Skipping steps causes orphaned memories.
+
+## Startup Sequence
+
+| Step | Call | Purpose |
+|------|------|---------|
+| 1 | `project_context(project)` | Load hot-tier memories, active decisions, adopted patterns |
+| 2 | `session_start(title, project)` | Begin tracking work (returns `session_id`) |
+| 3 | `decision_check(query, project)` | Check existing decisions before architectural choices |
+| 4 | `pattern_search(query)` | Find established conventions |
+
+## During Work
+
+| Action | Tool | Notes |
+|--------|------|-------|
+| Save info | `memory_store(content, metadata)` | Always set `deduplicate=true` |
+| Search | `memory_recall(query)` | Semantic search across memories |
+| Delete | `memory_forget(id_or_query)` | By ID or fuzzy search |
+| Browse | `memory_list(limit, offset)` | Chronological listing |
+| Read one | `memory_get(id)` | Fetch by exact ID |
+| Edit | `memory_update(id, content)` | Correct or expand existing |
+| Bulk save | `memory_batch_store(memories[])` | Efficient for multiple items |
+| Build prompt | `memory_context(query, token_budget)` | Token-aware context window |
+| Upgrade | `memory_promote(id, importance, tier)` | Move temporary to long-term |
+
+## Ending a Session
+
+Call `session_end(session_id, summary)` with a meaningful summary. This becomes the historical record.
+
+## Deduplication
+
+Always pass `deduplicate=true` on `memory_store` and `memory_batch_store`. The default threshold is 0.9 similarity. Skipping this clutters search results with near-duplicates.
+
+## Metadata Best Practices
+
+Always include `category` and `tags` in metadata:
+
+```
+metadata: { "category": "technical", "tags": "auth, api", "source": "code-review" }
+```
+
+Categories: `technical`, `preference`, `credential`, `decision`. Consistent metadata makes filtering reliable.
+
+## Memory Tiers and Promotion
+
+| Tier | Retention | Use for |
+|------|-----------|---------|
+| `hot` | Always loaded by `project_context` | Critical project facts |
+| `warm` | Retrieved by search | General knowledge |
+| `cold` | Archived, low priority | Historical notes |
+
+Use `memory_promote(id, importance, tier)` to upgrade a memory. Set `importance` near 1.0 for critical items.
+
+## Auto-Capture Tiers
+
+Configured per-plugin, not per-call. Know what mode is active:
+
+| Tier | Behavior |
+|------|----------|
+| `off` | No automatic capture |
+| `conservative` | Only credentials and explicit preferences |
+| `smart` (default) | Technical facts, preferences, patterns |
+| `aggressive` | Captures most exchanged information |
+
+## Privacy Blocklist
+
+Auto-filtered (never stored): passwords, credit card numbers, SSNs, API keys/tokens. The blocklist regex rejects these even on manual `memory_store` calls.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Storing without a session | Always call `session_start` first |
+| Skipping `deduplicate=true` | Set it on every `memory_store` call |
+| Using `memory_store` for decisions | Use `decision_record` instead |
+| No category/tags in metadata | Always include both for searchability |
+| Storing API keys or passwords | Blocklist rejects them; use a secrets manager |

package/skills/pattern-management/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: pattern-management
+description: "Use when establishing reusable conventions, looking up existing patterns before implementing a solution, adopting shared patterns across projects, or getting pattern recommendations for a project."
+---
+
+# Pattern Management
+
+Patterns are **reusable solutions with problem context**. Plain implementation notes are memories — use `memory_store` for those.
+
+## Pattern Tools
+
+| Tool | Signature | Purpose |
+|------|-----------|---------|
+| `pattern_create` | `pattern_create(title, description)` | Create a reusable pattern |
+| `pattern_search` | `pattern_search(query)` | Find existing patterns before creating new ones |
+| `pattern_adopt` | `pattern_adopt(pattern_id, project)` | Track which projects use which patterns |
+| `pattern_suggest` | `pattern_suggest(project)` | Get pattern recommendations for a project |
+
+## Workflow
+
+1. **Search first** — Always call `pattern_search(query)` before `pattern_create`. Duplicate patterns fragment conventions and confuse future lookups.
+2. **Create with structure** — If no match exists, call `pattern_create(title, description)`. The description must follow the structure below.
+3. **Adopt to projects** — Call `pattern_adopt(pattern_id, project)` so the pattern appears in `project_context` results and `pattern_suggest` recommendations.
+4. **Review suggestions** — Use `pattern_suggest(project)` when starting work on a project to discover applicable conventions.
+
+## Pattern Structure
+
+Every `description` in `pattern_create` should include:
+
+| Section | Content |
+|---------|---------|
+| **Problem** | What recurring issue this solves |
+| **Solution** | The reusable approach or convention |
+| **Context** | When to apply (and when not to) |
+| **Examples** | Concrete usage showing the pattern in action |
+
+```
+description: "Problem: Inconsistent error responses across API endpoints.
+Solution: Return { error: string, code: string, details?: object } on all 4xx/5xx.
+Context: REST APIs with multiple consumers. Not needed for internal RPC.
+Examples: 400 → { error: 'Invalid email', code: 'VALIDATION_ERROR' }"
+```
+
+## Cross-Project Consistency
+
+- `pattern_adopt(pattern_id, project)` links a pattern to a project. Multiple projects can adopt the same pattern.
+- `pattern_suggest(project)` returns unadopted patterns that may be relevant based on project context.
+- Adopted patterns load automatically via `project_context`, keeping teams aligned without manual lookups.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Creating without searching first | Always `pattern_search` before `pattern_create` — duplicates fragment conventions |
+| Vague descriptions | Follow the Problem/Solution/Context/Examples structure; be specific and actionable |
+| Not adopting to projects | Call `pattern_adopt` after creating; unadopted patterns are invisible to `project_context` |
+| Patterns too specific | Patterns should generalize across contexts; one-off solutions belong in memories or decisions |

package/skills/project-orchestration/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: project-orchestration
+description: "Use when registering a new project, loading project context before starting work, checking cross-project dependencies or impact before breaking changes, or managing relationships between projects."
+---
+
+# Project Orchestration
+
+Projects are the top-level organizer. Every session, memory, decision, and pattern ties back to a project slug.
+
+## Project Tools
+
+| Tool | Signature | Purpose |
+|------|-----------|---------|
+| `project_register` | `project_register(slug, name, description, stack)` | Register a new project |
+| `project_list` | `project_list()` | List all registered projects |
+| `project_info` | `project_info(slug)` | Get project details |
+| `project_add_relationship` | `project_add_relationship(from, to, type)` | Link related projects |
+| `project_dependencies` | `project_dependencies(slug)` | What this project depends on |
+| `project_dependents` | `project_dependents(slug)` | What depends on this project |
+| `project_related` | `project_related(slug)` | All related projects (any direction) |
+| `project_impact` | `project_impact(slug)` | Impact analysis before breaking changes |
+| `project_shared_patterns` | `project_shared_patterns(slug)` | Patterns shared across related projects |
+| `project_context` | `project_context(slug)` | Full overview: hot-tier memories, active decisions, adopted patterns |
+
+## First-Time Setup
+
+1. Call `project_list()` to see existing projects.
+2. If your project is not listed, call `project_register(slug, name, description, stack)`.
+3. If it exists, proceed — do not register duplicates.
+
+## defaultProject Config
+
+When `defaultProject` is set in plugin configuration, the project slug is **auto-applied** to sessions, decisions, and memories. You do not need to pass the project parameter explicitly on each call — it is injected automatically.
+
+## Context Loading
+
+Always call `project_context(slug)` as the **first step** when beginning work on a project. It returns:
+
+- **Hot-tier memories** — critical facts always surfaced
+- **Active decisions** — current architectural choices
+- **Adopted patterns** — conventions in use
+
+This replaces manual searching. Start here, then drill into specifics with other tools.
+
+## Impact Analysis
+
+Before making **any breaking change**, call `project_impact(slug)`. It checks:
+
+- Downstream dependents that will be affected
+- Shared patterns that may need updating
+- Active decisions that may conflict
+
+Never skip this step. Breaking a dependency without checking impact creates cascading failures.
+
+## Managing Relationships
+
+Use `project_add_relationship(from, to, type)` to declare how projects relate. Relationship types include dependencies, shared ownership, and related context. Once linked:
+
+- `project_dependencies(slug)` — upstream projects this one relies on
+- `project_dependents(slug)` — downstream projects relying on this one
+- `project_related(slug)` — all connections regardless of direction
+- `project_shared_patterns(slug)` — patterns adopted by both this project and its related projects
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Working without project context | Always `project_context` first — it loads everything you need |
+| Registering duplicate projects | Call `project_list` before `project_register`; check if slug exists |
+| Not using relationships | Call `project_add_relationship` when projects share code, APIs, or conventions |
+| Breaking changes without impact check | Always `project_impact` before modifying shared interfaces or dependencies |
+| Passing project on every call when `defaultProject` is set | Unnecessary — the config injects it automatically |

package/skills/release-process/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: release-process
+description: "Use when bumping the plugin version, preparing a release, updating the CHANGELOG, creating a pre-release audit branch, or triggering the NPM publish workflow."
+---
+
+# Release Process
+
+## Semantic Versioning (0.x series)
+
+| Bump | When | Example |
+|------|------|---------|
+| **Patch** (0.x.Y) | Bug fixes, version string updates, doc fixes | 0.12.10 → 0.12.11 |
+| **Minor** (0.X.0) | New tools, new features, new config options | 0.12.11 → 0.13.0 |
+| **Major** (X.0.0) | Breaking API changes (not used yet) | 0.13.0 → 1.0.0 |
+
+## Version Bump Locations
+
+All three files must match the same version string:
+
+| File | Field |
+|------|-------|
+| `package.json` | `"version": "X.Y.Z"` |
+| `openclaw.plugin.json` | `"version": "X.Y.Z"` and description string |
+| `index.ts` | Header comment `Version: X.Y.Z` |
+
+## CHANGELOG.md Format
+
+Follows [Keep a Changelog](https://keepachangelog.com/). Each release entry:
+
+```markdown
+## [X.Y.Z] - YYYY-MM-DD
+### Added
+- **Feature Name**: Description
+### Changed
+- Description
+### Fixed
+- **Bug Name**: Description
+```
+
+Add a comparison link at the bottom of the file:
+
+```
+[X.Y.Z]: https://github.com/memoryrelay/openclaw-plugin/compare/vPREV...vX.Y.Z
+```
+
+## Git Commit Conventions
+
+| Prefix | Use |
+|--------|-----|
+| `feat:` | New features or tools |
+| `fix:` | Bug fixes |
+| `docs:` | Documentation changes |
+| `chore:` | Maintenance, deps, cleanup |
+
+## CI/CD Workflows
+
+| File | Trigger | Purpose |
+|------|---------|---------|
+| `.github/workflows/ci.yml` | Push/PR to main | Tests on Node 20.x + 22.x matrix |
+| `.github/workflows/ci-cd.yml` | Push/PR | Full CI/CD pipeline |
+| `.github/workflows/publish.yml` | Manual dispatch | NPM publish with version verification |
+
+The publish workflow runs `npm publish --provenance --access public` and requires the `NPM_TOKEN` secret.
+
+## Pre-Release Audit Branch
+
+For doc review before release, create an audit branch:
+
+```
+docs/pre-release-audit-v{version}
+```
+
+Example: `docs/pre-release-audit-v0.12.11`. Merge to main once the audit is complete.
+
+## Release Checklist
+
+1. Update version in all 3 locations (`package.json`, `openclaw.plugin.json`, `index.ts`)
+2. Update `CHANGELOG.md` with new entry and comparison link
+3. Run `npm test` -- all tests must pass
+4. Create audit branch (`docs/pre-release-audit-v{version}`) if doc changes are needed
+5. Merge audit branch to main
+6. Trigger the `publish.yml` workflow manually from GitHub Actions
+7. Verify the published package on NPM

package/skills/testing-memoryrelay/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: testing-memoryrelay
+description: "Use when writing, running, or debugging tests for the MemoryRelay plugin, adding test coverage for new tools or hooks, or investigating test failures."
+---
+
+# Testing MemoryRelay
+
+Test runner: **Vitest**. All tests run without a live API.
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `npm test` | Run all tests once (`vitest run`) |
+| `npm run test:watch` | Watch mode (`vitest`) |
+| `npm run test:coverage` | Coverage report (`vitest run --coverage`) |
+
+## Test Files
+
+| File | Scope |
+|------|-------|
+| `index.test.ts` | Integration tests: API client, tools, hooks, retry logic, pattern detection, channel filtering, tool groups, workflow instructions |
+| `src/debug-logger.test.ts` | DebugLogger unit tests: circular buffer, filtering by tool/status, stats, formatting |
+| `src/status-reporter.test.ts` | StatusReporter unit tests: failure tracking, report building, formatting |
+
+## Mock Pattern
+
+Tests use `MockMemoryRelayClient` -- an in-memory implementation that replaces the real API client:
+
+```typescript
+import { describe, test, expect, beforeEach, vi } from "vitest";
+
+class MockMemoryRelayClient {
+  private memories: Memory[] = [];
+  private nextId = 1;
+  async store(content, metadata?) { /* push to array, return Memory */ }
+  async search(query, limit?, threshold?) { /* keyword .includes() match */ }
+  async list(limit?, offset?) { /* .slice() */ }
+  async get(id) { /* .find(), throws if missing */ }
+  async delete(id) { /* .splice(), throws if missing */ }
+  async health() { return { status: "healthy" }; }
+  async stats() { return { total_memories: this.memories.length }; }
+}
+```
+
+Instantiate fresh per test with `beforeEach(() => { client = new MockMemoryRelayClient("test_key", "test_agent"); })`.
+
+## What to Test per Tool
+
+| Area | Checks |
+|------|--------|
+| Input validation | Required params present, types correct |
+| Success path | API response formatted correctly, data stored/returned |
+| Error handling | Non-existent IDs throw, empty results return `[]` |
+| Deduplication | `deduplicate=true` prevents near-duplicate storage |
+| Session injection | `session_id` auto-applied from active session |
+| Retry logic | Network errors and 5xx retried; 4xx not retried |
+| Timeouts | 30s timeout via `AbortController` |
+
+## Testing Hooks
+
+**`before_agent_start`** -- workflow injection and auto-recall:
+
+- Verify workflow instructions are built from enabled tool groups
+- Mock `client.search()` to test auto-recall injects context
+- Test channel exclusion skips auto-recall for blocklisted channels
+
+**`agent_end`** -- auto-capture:
+
+- Test pattern detection (`shouldCapture`) with regex matching
+- Verify length bounds (20-2000 chars)
+- Confirm privacy blocklist rejects passwords, SSNs, API keys
+- Test tier logic: `off`, `conservative`, `smart`, `aggressive`
+
+## Testing Gateway Methods
+
+| Check | How |
+|-------|-----|
+| Response format | Assert returned object shape matches API contract |
+| Error surfaces | `detail` field extracted (FastAPI format), falls back to `message` |
+| HTTP method | GET with query params for search/check; POST with body for create/link |
+
+## Unit Test Patterns
+
+**DebugLogger**: Uses `vi.mock("fs")`. Test circular buffer (`maxEntries`), `getRecentLogs(n)`, `getToolLogs(name)`, `getErrorLogs()`, `getStats()`, `clear()`, `formatEntry()`.
+
+**StatusReporter**: Instantiate with real `DebugLogger`. Test `recordFailure`/`recordSuccess` toggle, `buildReport` shape, `formatReport`/`formatCompact` output, disconnected status handling.