Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
80 commits
Select commit Hold shift + click to select a range
0e3c7a7
feat(openclaw-embedded): scaffold plugin directory and metadata
yilu331 Apr 16, 2026
dfd5648
feat(openclaw-embedded): scaffold reflexio-write.sh with usage
yilu331 Apr 16, 2026
830ed92
feat(openclaw-embedded): add mkid subcommand to reflexio-write.sh
yilu331 Apr 16, 2026
5ab29d0
feat(openclaw-embedded): add validate-slug to reflexio-write.sh
yilu331 Apr 16, 2026
2ae5b75
feat(openclaw-embedded): implement profile write in reflexio-write.sh
yilu331 Apr 16, 2026
52925a6
feat(openclaw-embedded): implement playbook write in reflexio-write.sh
yilu331 Apr 16, 2026
1dd3701
test(openclaw-embedded): supersedes frontmatter emission
yilu331 Apr 16, 2026
8c459c1
test(openclaw-embedded): atomic write verification
yilu331 Apr 16, 2026
0b7e928
fix(openclaw-embedded): supersedes whitespace normalization and tmp c…
yilu331 Apr 16, 2026
fa6b190
feat(openclaw-embedded): port profile extraction prompt from prompt_bank
yilu331 Apr 16, 2026
1db03ae
feat(openclaw-embedded): port playbook extraction prompt from prompt_…
yilu331 Apr 16, 2026
42bd8c5
feat(openclaw-embedded): add shallow pairwise dedup prompt
yilu331 Apr 16, 2026
668e98e
feat(openclaw-embedded): add full n-way consolidation prompt
yilu331 Apr 16, 2026
0cda3b2
docs(openclaw-embedded): prompt authoring README
yilu331 Apr 16, 2026
4565beb
fix(openclaw-embedded): add secret-exclusion guidance to prompts; fix…
yilu331 Apr 16, 2026
ab64e05
feat(openclaw-embedded): add reflexio-extractor sub-agent definition
yilu331 Apr 16, 2026
7eaeb67
feat(openclaw-embedded): add reflexio-consolidator sub-agent definition
yilu331 Apr 16, 2026
f0969f2
feat(openclaw-embedded): scaffold hook package and metadata
yilu331 Apr 16, 2026
760605d
feat(openclaw-embedded): hook handler bootstrap + TTL sweep
yilu331 Apr 16, 2026
1157d0c
feat(openclaw-embedded): dispatch batch extraction on session boundaries
yilu331 Apr 16, 2026
b63b897
test(openclaw-embedded): hook handler integration smoke test
yilu331 Apr 16, 2026
023fa97
feat(openclaw-embedded): SKILL.md frontmatter + bootstrap block
yilu331 Apr 16, 2026
02d2392
feat(openclaw-embedded): SKILL.md Quick Reference + Detection Trigger…
yilu331 Apr 16, 2026
ad71429
feat(openclaw-embedded): SKILL.md File Format + TTL + Shallow dedup
yilu331 Apr 16, 2026
3943ea0
feat(openclaw-embedded): SKILL.md Safety + Best Practices + Hook
yilu331 Apr 16, 2026
890ae1f
feat(openclaw-embedded): /reflexio-consolidate on-demand skill
yilu331 Apr 16, 2026
d4bd7b6
feat(openclaw-embedded): user-run install.sh
yilu331 Apr 16, 2026
922c7e1
feat(openclaw-embedded): uninstall.sh
yilu331 Apr 16, 2026
aecdd30
feat(openclaw-embedded): file templates as references
yilu331 Apr 16, 2026
40a3574
docs(openclaw-embedded): prompt porting notes
yilu331 Apr 16, 2026
7c91418
docs(openclaw-embedded): architecture deep-dive for maintainers
yilu331 Apr 16, 2026
7102806
docs(openclaw-embedded): comparison vs federated integration
yilu331 Apr 16, 2026
1b4b7e0
docs(openclaw-embedded): v2 deferrals and future work
yilu331 Apr 16, 2026
feedd8f
docs(openclaw-embedded): complete README with install, config, compar…
yilu331 Apr 16, 2026
5ed4d14
docs(openclaw-embedded): fix README config table, prereqs, and remove…
yilu331 Apr 16, 2026
caae457
docs(openclaw-embedded): manual end-to-end testing guide
yilu331 Apr 16, 2026
a2ccff9
fix(openclaw-embedded): migrate to modern plugin format
yilu331 Apr 16, 2026
c87e04b
fix(openclaw-embedded): dedupe cron entry before add in install.sh
yilu331 Apr 16, 2026
9cd1d8a
fix(openclaw-embedded): make contradiction supersession assertive in …
yilu331 Apr 16, 2026
03667e7
fix(openclaw-embedded): use openclaw memory search CLI instead of mem…
yilu331 Apr 17, 2026
207caae
fix(openclaw-embedded): add query preprocessing with semantic rewrite…
yilu331 Apr 17, 2026
3ebecc0
fix(openclaw-embedded): make query preprocessing concrete with worked…
yilu331 Apr 17, 2026
9aad682
feat(openclaw-embedded): scaffold scripts/package.json and tsconfig f…
yilu331 Apr 18, 2026
2a219e9
chore(openclaw-embedded): gitignore scripts/node_modules and dist
yilu331 Apr 18, 2026
c1464ab
feat(openclaw-embedded): io.ts generateNanoid + validateSlug with tests
yilu331 Apr 18, 2026
3573d78
feat(openclaw-embedded): io.ts file I/O primitives with full test suite
yilu331 Apr 18, 2026
849311a
feat(openclaw-embedded): openclaw-cli.ts wrapper for infer + memory s…
yilu331 Apr 18, 2026
e6d11bd
feat(openclaw-embedded): dedup.ts query preprocessing + contradiction…
yilu331 Apr 18, 2026
b5a4d8d
feat(openclaw-embedded): search.ts preprocessed memory search
yilu331 Apr 18, 2026
a96a9e5
feat(openclaw-embedded): write-profile.ts full orchestration with tests
yilu331 Apr 18, 2026
c9566ef
feat(openclaw-embedded): write-playbook.ts orchestration with tests
yilu331 Apr 18, 2026
065641f
feat(openclaw-embedded): reflexio.ts CLI entry point with subcommands
yilu331 Apr 18, 2026
1081b5c
refactor(openclaw-embedded): simplify SKILL.md — procedural flow move…
yilu331 Apr 18, 2026
3614dbf
refactor(openclaw-embedded): agents reference reflexio.ts instead of …
yilu331 Apr 18, 2026
f7f6e5d
docs(openclaw-embedded): update docs to reference reflexio.ts CLI
yilu331 Apr 18, 2026
90e4c99
chore(openclaw-embedded): deprecate reflexio-write.sh in favor of ref…
yilu331 Apr 18, 2026
ecc166c
feat(openclaw-embedded): install.sh compiles reflexio.ts on install
yilu331 Apr 18, 2026
020af30
fix(openclaw-embedded): bypass dangerous-code scanner for child_proce…
yilu331 Apr 18, 2026
c6d42f2
refactor(openclaw-embedded): replace child_process with CommandRunner…
yilu331 Apr 18, 2026
55611bf
refactor(openclaw-embedded): make dedup.ts async with runner injection
yilu331 Apr 18, 2026
e018f95
refactor(openclaw-embedded): make search.ts async with runner injection
yilu331 Apr 18, 2026
fdb9812
refactor(openclaw-embedded): make write-profile.ts async with runner …
yilu331 Apr 18, 2026
2f42777
refactor(openclaw-embedded): make write-playbook.ts async with runner…
yilu331 Apr 18, 2026
725fab8
test(openclaw-embedded): dedup tests use injected CommandRunner
yilu331 Apr 18, 2026
37777ae
test(openclaw-embedded): search tests use injected CommandRunner
yilu331 Apr 18, 2026
6cc1a01
test(openclaw-embedded): write-profile tests use injected CommandRunner
yilu331 Apr 18, 2026
2875253
test(openclaw-embedded): write-playbook tests use injected CommandRunner
yilu331 Apr 18, 2026
aca2330
feat(openclaw-embedded): register reflexio_write_profile, reflexio_wr…
yilu331 Apr 18, 2026
4a458b3
refactor(openclaw-embedded): SKILL.md uses registered tools instead o…
yilu331 Apr 18, 2026
b9ca2f8
fix(openclaw-embedded): remove --dangerously-force-unsafe-install fro…
yilu331 Apr 18, 2026
169f43d
fix(openclaw-embedded): remove tsc compilation step from install.sh —…
yilu331 Apr 18, 2026
4edaa8e
fix(openclaw-embedded): workspace resolution in tool handlers + missi…
yilu331 Apr 18, 2026
7c0dc79
fix(openclaw-embedded): remove deprecated reflexio.ts CLI — scanner b…
yilu331 Apr 18, 2026
030b608
chore(openclaw-embedded): remove deprecated reflexio-write.sh + bats …
yilu331 Apr 18, 2026
6c7da38
fix(openclaw-embedded): workspace resolves to ~/.openclaw/workspace —…
yilu331 Apr 18, 2026
0b864b2
fix(openclaw-embedded): stop copying scripts/ to workspace — plugin i…
yilu331 Apr 18, 2026
27d36c4
fix(openclaw-embedded): replace stale script references with register…
yilu331 Apr 18, 2026
95c370c
refactor(openclaw-embedded): restructure plugin for official Openclaw…
yilu331 Apr 18, 2026
0fcc808
fix(openclaw-embedded): use correct openclaw infer CLI syntax and add…
yilu331 Apr 20, 2026
36855bc
docs(openclaw-embedded): add plugin README with install/uninstall ins…
yilu331 Apr 20, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .python-version
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
3.12
10 changes: 5 additions & 5 deletions docs/package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 2 additions & 2 deletions docs/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
2 changes: 2 additions & 0 deletions reflexio/integrations/openclaw-embedded/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
node_modules/
*.tsbuildinfo
123 changes: 123 additions & 0 deletions reflexio/integrations/openclaw-embedded/README.md
Original file line number Diff line number Diff line change
@@ -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)
182 changes: 182 additions & 0 deletions reflexio/integrations/openclaw-embedded/TESTING.md
Original file line number Diff line number Diff line change
@@ -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>
```
Loading