# Phase 4 — Ecosystem Integration (v4.0) Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Package Memory Continuity for OpenClaw marketplace publishing, declare complementary positioning with lossless-claw, and expose a programmatic skill interface so other plugins can call `/mc recall`.

**Architecture:** Three independent additions — (1) marketplace metadata in manifests + README update, (2) interop declaration via `openclaw.plugin.json` `interop` field and docs, (3) a new `api.exposeService()` call in the lifecycle plugin that other plugins can query for recall results without going through the slash command.

**Tech Stack:** Node.js ESM, OpenClaw plugin API (`api.exposeService`, `api.registerCommand`), markdown files, zero external deps.

---

## File Structure

| Action | File | Responsibility |
|--------|------|----------------|
| Modify | `openclaw.plugin.json` | Add marketplace metadata fields (author, license, icon, category, interop) |
| Modify | `package.json` | Bump to 4.0.0, add marketplace fields |
| Modify | `mc-plugin/package.json` | Bump to 2.0.0 |
| Modify | `mc-plugin/openclaw.plugin.json` | Bump to 2.0.0, add marketplace category |
| Modify | `index.js` | Add `api.exposeService("mc:recall", ...)` in `register()` |
| Modify | `README.md` | Update version, add marketplace install section, interop docs, skill API docs |
| Create | `MARKETPLACE.md` | Marketplace listing long description (separate from README for marketplace scraping) |

---

### Task 1: Marketplace Metadata for Lifecycle Plugin

**Files:**
- Modify: `openclaw.plugin.json`
- Modify: `package.json`

The OpenClaw `plugins install` command supports `--marketplace <source>` and `openclaw plugins marketplace list <source>`. The manifest needs enriched metadata for discoverability.

- [ ] **Step 1: Add marketplace fields to `openclaw.plugin.json`**

Open `openclaw.plugin.json` and add the following fields alongside the existing content:

```json
{
  "id": "memory-continuity",
  "name": "Memory Continuity",
  "description": "Preserves working state across /new, reset, compaction, and gateway restarts via a simple markdown checkpoint file.",
  "version": "4.0.0",
  "author": {
    "name": "dtzp555-max",
    "url": "https://github.com/dtzp555-max"
  },
  "license": "MIT",
  "repository": "https://github.com/dtzp555-max/memory-continuity",
  "category": "memory",
  "tags": ["memory", "continuity", "state", "recovery", "markdown", "zero-dependency"],
  "icon": "brain",
  "minOpenClawVersion": "2026.3.0",
  "source": "https://github.com/dtzp555-max/memory-continuity",
  "configSchema": { ... existing configSchema unchanged ... },
  "uiHints": { ... existing uiHints unchanged ... }
}
```

Key additions:
- `author` — object with name and URL
- `license` — MIT
- `category` — "memory" (standard marketplace category)
- `tags` — array for search/filter
- `icon` — emoji-name for UI display
- `minOpenClawVersion` — minimum compatible version

- [ ] **Step 2: Update `package.json` to v4.0.0**

```json
{
  "name": "memory-continuity",
  "version": "4.0.0",
  "description": "Zero-dependency memory continuity for OpenClaw — plain markdown, lifecycle hooks, no vector DB.",
  "main": "index.js",
  "type": "module",
  "repository": {
    "type": "git",
    "url": "https://github.com/dtzp555-max/memory-continuity.git"
  },
  "keywords": ["openclaw", "plugin", "memory", "continuity", "state", "recovery", "markdown"],
  "author": "dtzp555-max",
  "license": "MIT",
  "openclaw": {
    "type": "plugin",
    "id": "memory-continuity",
    "pluginManifest": "openclaw.plugin.json"
  }
}
```

- [ ] **Step 3: Verify plugin still loads**

```bash
cd ~/.openclaw/projects/memory-continuity
node -e "import('./index.js').then(m => console.log('OK:', typeof m.default))"
```

Expected: `OK: object`

- [ ] **Step 4: Commit**

```bash
git add openclaw.plugin.json package.json
git commit -m "feat(marketplace): add marketplace metadata to lifecycle plugin manifest"
```

---

### Task 2: Marketplace Metadata for MC Commands Plugin

**Files:**
- Modify: `mc-plugin/openclaw.plugin.json`
- Modify: `mc-plugin/package.json`

- [ ] **Step 1: Add marketplace fields to `mc-plugin/openclaw.plugin.json`**

```json
{
  "id": "mc",
  "name": "Memory Continuity Commands",
  "description": "Slash commands for Memory Continuity — /mc state, /mc history, /mc search, /mc recall, /mc settings, etc.",
  "version": "2.0.0",
  "author": {
    "name": "dtzp555-max",
    "url": "https://github.com/dtzp555-max"
  },
  "license": "MIT",
  "category": "commands",
  "tags": ["memory", "commands", "search", "recall"],
  "icon": "terminal",
  "requires": ["memory-continuity"],
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "memoryDir": {
        "type": "string",
        "default": "",
        "description": "Override memory directory path (auto-detected from workspace if empty)"
      }
    }
  }
}
```

Key addition: `requires` — declares dependency on the `memory-continuity` lifecycle plugin.

- [ ] **Step 2: Bump `mc-plugin/package.json` to 2.0.0**

```json
{
  "name": "mc-plugin",
  "version": "2.0.0",
  "description": "Slash commands for Memory Continuity — /mc state, /mc history, /mc search, etc.",
  "main": "index.js",
  "type": "module",
  "keywords": ["openclaw", "plugin", "memory", "continuity", "commands"],
  "license": "MIT",
  "openclaw": {
    "type": "plugin",
    "id": "mc",
    "pluginManifest": "openclaw.plugin.json"
  }
}
```

- [ ] **Step 3: Verify mc-plugin still loads**

```bash
cd ~/.openclaw/projects/memory-continuity/mc-plugin
node -e "import('./index.js').then(m => console.log('OK:', typeof m.default))"
```

Expected: `OK: function`

- [ ] **Step 4: Commit**

```bash
git add mc-plugin/openclaw.plugin.json mc-plugin/package.json
git commit -m "feat(marketplace): add marketplace metadata to mc-plugin manifest"
```

---

### Task 3: lossless-claw Interop Declaration

**Files:**
- Modify: `openclaw.plugin.json` (add `interop` field)
- Create: `MARKETPLACE.md`

The key design point: MC uses lifecycle hooks (not the `contextEngine` slot), so it coexists with lossless-claw. MC handles working-state recovery; lossless-claw handles full context compression. They complement each other.

- [ ] **Step 1: Add `interop` field to `openclaw.plugin.json`**

Add the following field to the root of the manifest (after `minOpenClawVersion`):

```json
  "interop": {
    "complements": [
      {
        "id": "lossless-claw",
        "reason": "MC uses lifecycle hooks for working-state recovery; lossless-claw uses the contextEngine slot for lossless context compression. They occupy different plugin slots and serve different purposes — install both for best results."
      }
    ],
    "conflicts": [],
    "slot": "hooks-only",
    "slotNote": "Does NOT occupy the contextEngine slot. Safe to run alongside any context engine."
  }
```

- [ ] **Step 2: Create `MARKETPLACE.md`**

This file provides the long-form marketplace listing description (separate from README which is for developers).

```markdown
# Memory Continuity — Marketplace Listing

## What it does

Memory Continuity is a **zero-dependency lifecycle plugin** that preserves your working state across session resets, compaction, and gateway restarts. It answers one question:

> What were we doing, where did we stop, and what should happen next?

## Key features

- **Automatic state checkpoint** — saves working state at session end, before `/new`, and before compaction
- **Session logging** — daily markdown logs of all sessions with topic, message count, and token estimates
- **Layered summaries** — daily summaries roll up into weekly summaries
- **Tag extraction** — `#tag` patterns auto-indexed in `memory/tags.md`
- **Relevance injection** — injects related history at session start based on keyword matching
- **Memory decay** — old archives move to cold storage after configurable days
- **CJK-aware** — proper token estimation for Chinese/Japanese/Korean text
- **Search & recall** — `/mc search` and `/mc recall` for cross-memory search

## Why this plugin?

| Feature | Memory Continuity | Other memory plugins |
|---------|------------------|---------------------|
| Dependencies | Zero | SQLite, Chroma, APIs |
| Data format | Plain markdown | Proprietary DB |
| Backup strategy | `cp` / `scp` | DB export |
| Migration | Copy files | Re-index |
| contextEngine slot | Not used | Often required |
| Works with lossless-claw | Yes | Varies |

## Works with lossless-claw

MC intentionally does NOT use the `contextEngine` slot. It runs via lifecycle hooks only. This means you can install both:

- **lossless-claw** — lossless context compression (contextEngine slot)
- **memory-continuity** — working-state recovery (hooks only)

They serve complementary purposes and never conflict.

## Install

```bash
openclaw plugins install https://github.com/dtzp555-max/memory-continuity
```

## Configuration

All settings are optional with sensible defaults. See `openclaw plugins inspect memory-continuity` for the full config schema.
```

- [ ] **Step 3: Commit**

```bash
git add openclaw.plugin.json MARKETPLACE.md
git commit -m "feat(interop): declare lossless-claw complementary positioning + marketplace listing"
```

---

### Task 4: Programmatic Skill Interface — `mc:recall` Service

**Files:**
- Modify: `index.js` (add `api.exposeService` in `register()`)

The goal: other plugins can programmatically call `api.getService("mc:recall")` to get recall results as structured data, without parsing slash command output.

- [ ] **Step 1: Add the `findRelevantHistory` re-export as a service**

At the end of the `register(api)` function in `index.js`, before the final log line, add:

```javascript
    // ------------------------------------------------------------------
    // SERVICE: mc:recall — programmatic interface for other plugins
    // ------------------------------------------------------------------
    if (typeof api.exposeService === "function") {
      api.exposeService("mc:recall", {
        description: "Search memory history by topic keywords. Returns scored results.",

        /**
         * @param {Object} params
         * @param {string} params.topic - Keywords to search for
         * @param {number} [params.maxItems=5] - Maximum results to return
         * @param {string} [params.format="structured"] - "structured" returns array of objects, "text" returns formatted string
         * @returns {{ results: Array<{ date: string, type: string, score: number, summary: string }>, total: number }}
         */
        async handler(params, ctx) {
          const topic = params?.topic;
          if (!topic || typeof topic !== "string") {
            return { error: "topic (string) is required", results: [], total: 0 };
          }

          const ws = ctx?.workspaceDir;
          if (!ws) {
            return { error: "no workspace context", results: [], total: 0 };
          }

          const maxItems = Math.min(params?.maxItems ?? 5, 20);

          // Reuse the internal findRelevantHistory function
          const textResult = findRelevantHistory(ws, topic, maxItems);

          if (!textResult) {
            return { results: [], total: 0 };
          }

          // For "text" format, return the raw string (same as before_agent_start injection)
          if (params?.format === "text") {
            return { text: textResult, total: 1 };
          }

          // For "structured" format, parse the result into objects
          const lines = textResult.split("\n").filter(l => l.startsWith("["));
          const results = lines.map(line => {
            const dateMatch = line.match(/^\[([^\]]+)\]/);
            const summary = line.replace(/^\[[^\]]+\]\s*/, "").trim();
            return {
              date: dateMatch?.[1] || "unknown",
              type: "history",
              score: 0,
              summary,
            };
          });

          return { results, total: results.length };
        },
      });

      log.info?.("[memory-continuity] Exposed mc:recall service for inter-plugin use");
    }
```

- [ ] **Step 2: Verify plugin still loads with the service**

```bash
cd ~/.openclaw/projects/memory-continuity
node -e "import('./index.js').then(m => console.log('OK:', typeof m.default, typeof m.default.register))"
```

Expected: `OK: object function`

- [ ] **Step 3: Commit**

```bash
git add index.js
git commit -m "feat(skill-api): expose mc:recall as programmatic service for inter-plugin use"
```

---

### Task 5: README Update

**Files:**
- Modify: `README.md`

- [ ] **Step 1: Update README header and install section**

Update the version line at the top:

```markdown
**Current release:** `v4.0.0`
```

Add after the existing "Quick Start" / "Install" section:

```markdown
### Marketplace Install (recommended)

```bash
openclaw plugins install https://github.com/dtzp555-max/memory-continuity
```

### Works with lossless-claw

This plugin does **not** use the `contextEngine` slot. It runs via lifecycle hooks only, so it coexists perfectly with lossless-claw or any other context engine:

- **lossless-claw** = lossless context compression (contextEngine slot)
- **memory-continuity** = working-state recovery (hooks only)

Install both for the best experience.

### Programmatic API

Other plugins can call MC's recall function programmatically:

```javascript
// In another plugin's register() function:
const recall = api.getService("mc:recall");
if (recall) {
  const result = await recall.handler(
    { topic: "deployment issues", maxItems: 3 },
    ctx
  );
  // result.results = [{ date, type, score, summary }, ...]
}
```
```

- [ ] **Step 2: Commit**

```bash
git add README.md
git commit -m "docs: update README with marketplace install, interop, and skill API sections"
```

---

### Task 6: Final Version Bump + Verification

**Files:**
- Verify: all modified files

- [ ] **Step 1: Verify all version numbers match**

```bash
grep '"version"' openclaw.plugin.json package.json mc-plugin/openclaw.plugin.json mc-plugin/package.json
```

Expected:
- `openclaw.plugin.json` → `"4.0.0"`
- `package.json` → `"4.0.0"`
- `mc-plugin/openclaw.plugin.json` → `"2.0.0"`
- `mc-plugin/package.json` → `"2.0.0"`

- [ ] **Step 2: Verify both plugins load**

```bash
cd ~/.openclaw/projects/memory-continuity
node -e "import('./index.js').then(m => console.log('lifecycle:', typeof m.default))"
node -e "import('./mc-plugin/index.js').then(m => console.log('mc-plugin:', typeof m.default))"
```

Expected:
```
lifecycle: object
mc-plugin: function
```

- [ ] **Step 3: Copy to extensions and restart gateway**

```bash
cp index.js package.json openclaw.plugin.json ~/.openclaw/extensions/memory-continuity/
cp mc-plugin/index.js mc-plugin/package.json mc-plugin/openclaw.plugin.json ~/.openclaw/extensions/mc/ 2>/dev/null
```

- [ ] **Step 4: Verify with `openclaw plugins inspect`**

```bash
openclaw plugins inspect memory-continuity
```

Expected: shows `Version: 4.0.0` and all 5 hooks.

- [ ] **Step 5: Final commit + tag**

```bash
git add -A
git commit -m "release: v4.0.0 — ecosystem integration (marketplace, interop, skill API)"
git tag v4.0.0
git push origin main --tags
```

---

### Task 7: Deploy to All 3 Servers

**Files:** None (deployment only)

- [ ] **Step 1: Deploy to Cloud (152.67.121.35)**

```bash
scp index.js package.json openclaw.plugin.json MARKETPLACE.md opc@152.67.121.35:~/.openclaw/extensions/memory-continuity/
scp mc-plugin/index.js mc-plugin/package.json mc-plugin/openclaw.plugin.json opc@152.67.121.35:~/.openclaw/extensions/mc/
ssh opc@152.67.121.35 "pkill -f 'openclaw.*gateway'; sleep 1; nohup openclaw gateway start > /dev/null 2>&1 &"
```

- [ ] **Step 2: Deploy to PI (172.16.2.232)**

```bash
scp index.js package.json openclaw.plugin.json MARKETPLACE.md administrator@172.16.2.232:~/.openclaw/extensions/memory-continuity/
scp mc-plugin/index.js mc-plugin/package.json mc-plugin/openclaw.plugin.json administrator@172.16.2.232:~/.openclaw/extensions/mc/
ssh administrator@172.16.2.232 "pkill -f 'openclaw.*gateway'; sleep 1; nohup openclaw gateway start > /dev/null 2>&1 &"
```

- [ ] **Step 3: Restart Mac gateway**

```bash
cp index.js package.json openclaw.plugin.json ~/.openclaw/extensions/memory-continuity/
pkill -f 'openclaw.*gateway'; sleep 1; nohup openclaw gateway start > /dev/null 2>&1 &
```

- [ ] **Step 4: Verify all 3 servers**

```bash
grep version ~/.openclaw/extensions/memory-continuity/package.json
ssh opc@152.67.121.35 "grep version ~/.openclaw/extensions/memory-continuity/package.json"
ssh administrator@172.16.2.232 "grep version ~/.openclaw/extensions/memory-continuity/package.json"
```

Expected: all show `"version": "4.0.0"`.