feat: openclaw-embedded plugin — aligned with official plugin guide

.python-version

@@ -0,0 +1 @@
+3.12

docs/package.json

@@ -25,8 +25,8 @@
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4",
-    "@types/node": "^20",
-    "@types/react": "^19",
+    "@types/node": "20.19.39",
+    "@types/react": "19.2.14",
     "@types/react-dom": "^19",
     "eslint": "^9",
     "eslint-config-next": "16.2.0",

reflexio/integrations/openclaw-embedded/.gitignore

@@ -0,0 +1,2 @@
+node_modules/
+*.tsbuildinfo

reflexio/integrations/openclaw-embedded/README.md

@@ -0,0 +1,123 @@
+# Reflexio OpenClaw-Embedded Plugin
+
+A lightweight Openclaw plugin that delivers Reflexio-style user profile and playbook capabilities entirely within Openclaw's native primitives — no Reflexio server required.
+
+## Table of Contents
+
+- [How It Works](#how-it-works)
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [First-use Setup](#first-use-setup)
+- [Configuration](#configuration)
+- [Comparison with Other Reflexio Integrations](#comparison-with-other-reflexio-integrations)
+- [Uninstall](#uninstall)
+- [Further Reading](#further-reading)
+
+## How It Works
+
+The plugin captures two kinds of memory:
+
+- **Profiles** — durable user facts (diet, preferences, timezone, role). Stored as `.md` files under `.reflexio/profiles/` with a TTL.
+- **Playbooks** — procedural rules learned from corrections (user corrects → agent adjusts → user confirms → rule written). Stored under `.reflexio/playbooks/`.
+
+Three flows capture memory at different moments:
+
+- **Flow A (in-session profile)**: agent detects a preference/fact/config in the user message and writes immediately.
+- **Flow B (in-session playbook)**: agent recognizes correction+confirmation multi-turn pattern and writes the rule.
+- **Flow C (session-end batch)**: hook fires on `session:compact:before` / `command:stop` / `command:reset`; spawns a sub-agent that extracts from the full transcript, runs shallow pairwise dedup, and writes/deletes `.md` files.
+
+A daily 3am cron job runs full-sweep consolidation (n-way cluster merges) across all files.
+
+All retrieval is via Openclaw's memory engine — vector + FTS + MMR + temporal decay. When Active Memory is enabled, relevant profiles/playbooks are auto-injected into each turn.
+
+## Prerequisites
+
+- [OpenClaw](https://openclaw.ai) installed and `openclaw` CLI on PATH
+- Node.js (for the plugin runtime)
+- macOS or Linux (Windows via WSL)
+- A bash-compatible shell (install/uninstall scripts use `#!/usr/bin/env bash`)
+- Strongly recommended:
+  - An embedding provider API key (OpenAI, Gemini, Voyage, or Mistral) for vector search
+  - The `active-memory` plugin enabled (auto-retrieval into turns)
+
+The plugin works without active-memory and without an embedding key — with degraded retrieval quality. See `references/architecture.md` for degradation modes.
+
+## Installation
+
+```bash
+# From the plugin directory:
+./scripts/install.sh
+```
+
+What it does:
+1. Installs and links the `plugin/` directory as an Openclaw plugin
+2. Copies SKILL.md, consolidate skill, and agent definitions to workspace
+3. Copies prompts to workspace
+4. Enables the `active-memory` plugin and configures agent targeting + extraPath
+5. Registers a daily 3am consolidation cron
+6. Restarts the Openclaw gateway
+7. Prints verification commands
+
+## First-use Setup
+
+The first time an agent invokes the `reflexio-embedded` skill, it runs a one-time bootstrap:
+
+1. Probes current config via `openclaw config get` + `openclaw memory status --deep`.
+2. For any missing prereq, asks the user for approval before running `openclaw config set` via the `exec` tool.
+3. On success, creates `.reflexio/.setup_complete_<agentId>` marker — subsequent sessions skip.
+
+This guarantees zero manual `openclaw.json` editing. If `exec` is denied by admin policy, the skill prints the exact commands for the user to run manually.
+
+## Configuration
+
+Defaults live in `config.json`. To override, use one of:
+
+1. Edit `config.json` directly
+2. Use `openclaw config` for overrides persisted at the Openclaw layer
+
+(env var overrides are planned for v2; see `references/future-work.md`)
+
+Tunables:
+
+| Knob | Default | What it controls |
+|---|---|---|
+| `dedup.shallow_threshold` | 0.7 | Similarity above which in-session writes trigger pairwise dedup |
+| `dedup.full_threshold` | 0.75 | Similarity cluster-member cutoff in daily consolidation |
+| `dedup.top_k` | 5 | How many neighbors to consider |
+| `ttl_sweep.on_bootstrap` | `true` | Whether to sweep expired profiles on each agent bootstrap |
+| `consolidation.cron` | `"0 3 * * *"` | Daily consolidation schedule |
+| `extraction.subagent_timeout_seconds` | 120 | Flow C sub-agent timeout |
+
+### Tuning guidance
+
+| Symptom | Likely cause | Knob |
+|---|---|---|
+| Duplicate `.md` files accumulating between cron runs | Shallow threshold too high | Lower `shallow_threshold` (e.g., 0.65) |
+| Good-but-distinct entries getting merged | Thresholds too low | Raise both thresholds (e.g., 0.8) |
+| Daily consolidation takes too long | Too many / too broad clusters | Raise `full_threshold`, cap cluster size |
+| Session-end latency slightly noticeable | Too many shallow dedup LLM calls | Lower `top_k` to 3 |
+
+## Comparison with Other Reflexio Integrations
+
+See `references/comparison.md` for a full matrix.
+
+- **`integrations/openclaw-embedded/`** (this plugin): self-contained; no Reflexio server; single-user.
+- **`integrations/openclaw/`** (federated): requires running Reflexio server; multi-user; cross-instance aggregation.
+
+Both can coexist in the same Openclaw instance, but installing both serves no purpose — pick one.
+
+## Uninstall
+
+```bash
+./scripts/uninstall.sh           # preserves .reflexio/ user data
+./scripts/uninstall.sh --purge   # also deletes .reflexio/ user data
+```
+
+## Further Reading
+
+- [Design spec](../../../../docs/superpowers/specs/2026-04-16-reflexio-openclaw-embedded-plugin-design.md)
+- [Implementation plan](../../../../docs/superpowers/plans/2026-04-16-reflexio-openclaw-embedded-plugin.md)
+- [Architecture deep-dive](references/architecture.md)
+- [Prompt porting notes](references/porting-notes.md)
+- [Future work / v2 deferrals](references/future-work.md)
+- [Manual testing guide](TESTING.md)

reflexio/integrations/openclaw-embedded/TESTING.md

@@ -0,0 +1,182 @@
+# Manual Testing Guide
+
+End-to-end manual validation of `openclaw-embedded`. Run this before each release.
+
+## Prerequisites
+
+- A clean Openclaw instance (fresh workspace, or separate test workspace)
+- Node and openclaw CLI on PATH
+- An embedding provider configured (optional but recommended for full coverage)
+- A terminal with `bats` installed (for running shell unit tests)
+
+## 1. Unit tests
+
+From the `openclaw-embedded/` directory:
+
+```bash
+npm test
+```
+
+Expected: 47 tests pass. If any fail, stop — fix before proceeding.
+
+## 2. Hook smoke test
+
+```bash
+node plugin/hook/smoke-test.js
+```
+
+Expected: all PASS lines printed, no FAIL.
+
+## 3. Install plugin
+
+```bash
+./scripts/install.sh
+```
+
+Expected verification output:
+```
+  ✓ hook registered
+  ✓ cron registered
+```
+
+If any ⚠ warnings, investigate before moving on.
+
+## 4. First-use bootstrap
+
+- Open a new Openclaw agent session.
+- Say: "test the reflexio-embedded skill setup".
+- Expected: the agent invokes the skill, runs probing commands, asks for approval to configure active-memory and extraPath.
+- Approve each step.
+- Verify `.reflexio/.setup_complete_<agentId>` marker exists.
+
+## 5. Flow A — profile capture
+
+In the agent session:
+
+- Say: "By the way, I'm vegetarian."
+- Expected: agent writes `.reflexio/profiles/diet-vegetarian-<nanoid>.md` with:
+  - Frontmatter: `type: profile`, `id: prof_*`, `ttl: infinity`, `expires: never`
+  - Body: ~1-sentence description
+
+```bash
+cat .reflexio/profiles/diet-*.md
+```
+
+Verify the file matches expectations.
+
+## 6. Flow B — playbook capture
+
+- Say: "Write a commit message for 'fix auth bug'."
+- Expected: agent writes a commit message (may include Co-Authored-By).
+- Say: "No, don't add Co-Authored-By trailers."
+- Expected: agent rewrites without the trailer.
+- Say: "Perfect, commit it."
+- Expected: agent writes `.reflexio/playbooks/commit-no-ai-attribution-<nanoid>.md`.
+
+```bash
+cat .reflexio/playbooks/commit-*.md
+```
+
+Verify frontmatter + `## When` / `## What` / `## Why` sections.
+
+## 7. Flow C — batch extraction at session boundary
+
+- Have a longer conversation (5+ turns) covering facts and corrections.
+- Trigger `command:stop` (or let the session compact naturally).
+- Expected: the hook fires a `reflexio-extractor` sub-agent.
+
+Inspect via:
+```bash
+openclaw tasks list --agent reflexio-extractor
+```
+
+Expected: a completed task record exists.
+
+Check `.reflexio/profiles/` and `.reflexio/playbooks/` — new files should have appeared corresponding to any facts/corrections the agent missed in-session.
+
+## 8. Retrieval validation
+
+Start a new session. Ask: "What do you know about my diet?"
+
+- With Active Memory enabled: expected answer references "vegetarian" from the captured profile.
+- With Active Memory disabled: expected agent calls `memory_search` per SKILL.md fallback, then answers.
+
+## 9. Consolidation (on-demand)
+
+After accumulating 10+ entries across sessions, run:
+
+```
+/skill reflexio-consolidate
+```
+
+Expected:
+- Agent delegates to `reflexio-consolidator` sub-agent.
+- Returns a runId.
+
+Inspect:
+```bash
+openclaw tasks list --agent reflexio-consolidator
+```
+
+Check `.reflexio/` before and after — duplicate or overlapping entries should be collapsed, with `supersedes` frontmatter on merged files.
+
+## 10. TTL sweep
+
+- Create a profile with short TTL by calling the `reflexio_write_profile` tool (or via agent session):
+  ```
+  Call the `reflexio_write_profile` tool with: slug="test-temp", ttl="one_day", body="temp fact"
+  ```
+- Manually edit its `expires` to a past date:
+  ```bash
+  # Edit .reflexio/profiles/test-temp-*.md — set expires: 2020-01-01
+  ```
+- Restart the agent session (triggers `agent:bootstrap` hook).
+- Expected: the expired profile is deleted.
+
+## 11. Degradation: no Active Memory
+
+- Disable active-memory: `openclaw plugins disable active-memory`
+- Restart gateway.
+- Start new session, ask a question whose answer needs a captured profile.
+- Expected: agent calls `memory_search` explicitly (per SKILL.md fallback), then answers.
+- Re-enable: `openclaw plugins enable active-memory`.
+
+## 12. Degradation: no embedding provider
+
+- Unset embedding env vars.
+- Restart gateway.
+- Ask the agent something whose answer needs retrieval.
+- Expected: retrieval works via FTS only (quality lower but functional).
+
+## 13. Uninstall
+
+```bash
+./scripts/uninstall.sh
+```
+
+Verify:
+- `openclaw hooks list` does NOT include `reflexio-embedded`.
+- `openclaw cron list` does NOT include `reflexio-embedded-consolidate`.
+- `~/.openclaw/workspace/skills/reflexio-embedded/` does not exist.
+- `.reflexio/` in the workspace is preserved.
+
+Run `./scripts/uninstall.sh --purge` in a test workspace to verify `.reflexio/` is deleted.
+
+## Test report template
+
+When testing for a release:
+
+```
+Tested: <date> <tester>
+Openclaw version: <version>
+Unit tests: <pass/fail>
+Hook smoke test: <pass/fail>
+Flow A: <pass/fail — notes>
+Flow B: <pass/fail — notes>
+Flow C: <pass/fail — notes>
+Retrieval: <pass/fail — notes>
+Consolidation: <pass/fail — notes>
+TTL sweep: <pass/fail — notes>
+Degradation modes: <pass/fail — notes>
+Uninstall: <pass/fail — notes>
+```