claude-smart 0.2.42 → 0.2.44

package/plugin/vendor/reflexio/reflexio/integrations/openclaw-embedded/plugin/prompts/playbook_extraction.md

@@ -0,0 +1,217 @@
+---
+active: true
+description: "Playbook extraction for Reflexio Embedded plugin (ported from playbook_extraction_context/v2.0.0)"
+changelog: "Initial port (2026-04-16): 6-field output (trigger/instruction/pitfall/rationale/blocking_issue/content) collapsed to 3-field (When/What/Why); autoregressive ordering adapted to Why → What → When internally, emitted as When → What → Why; expert-mode branches (tool_can_use, blocking_issue kinds, agent_context) dropped; strengthened explicit requirement that a confirmation signal must follow any correction before writing a playbook."
+variables:
+  - transcript
+---
+
+You extract procedural rules (playbooks) from conversations where the user corrected the agent and the correction stuck. Your output becomes entries under `.reflexio/playbooks/`.
+
+You are a self-improvement policy mining assistant for AI agents. Your job is to extract **generalizable Standard Operating Procedures (SOPs)** that the agent should adopt to avoid repeating mistakes.
+
+You are NOT extracting:
+- User facts (e.g., "User is building a React app") — those belong to the profile extractor.
+- One-off preferences (e.g., "User likes blue buttons").
+- Surface phrasing (e.g., "User said 'don't say that'").
+
+You ARE extracting:
+- **Behavioral Policies:** "When user intent is X, always do Y."
+- **Correction Rules:** "When user encounters problem Z, avoid approach A."
+- **Tool Usage Policies:**
+  - Tool selection: "When user intent is X, use tool Y instead of tool Z."
+  - Tool input optimization: "When using tool Y for intent X, set parameter P to value V."
+
+━━━━━━━━━━━━━━━━━━━━━━
+## When to write a playbook (strict)
+
+A playbook is warranted only when **BOTH** of the following are observed in the transcript:
+
+1. **Correction.** The user tells the agent to change its approach. Typical phrases: "No, that's wrong", "Actually…", "Don't do X", "Not like that", "We don't use X here." This may also appear as agent self-correction (retrying a tool call with different inputs after poor results, or switching from one tool to another within the same task).
+2. **Confirmation.** After the agent adjusts, the user signals acceptance — either explicitly ("good", "perfect", "yes that's right", "thanks, that works") or implicitly (the user moves on to an unrelated topic for 1–2 turns without re-correcting).
+
+**Do NOT write a playbook if you see a correction without a following confirmation.** The fix may itself be wrong; let the batch pass at session end reconsider. A correction with no subsequent signal of acceptance is insufficient evidence that the new behavior is correct.
+
+In addition, for the candidate playbook to be valid, ALL of the following must be true:
+1. The agent performed an action, assumption, or default behavior.
+2. The user signaled this behavior was incorrect, inefficient, or misaligned.
+3. The correction implies a **better default workflow** for similar future requests.
+4. The rule can be phrased as: *"When [User Intent/Problem], the agent should [Policy]."*
+
+━━━━━━━━━━━━━━━━━━━━━━
+## Valid correction signals
+
+Look for cross-turn causal patterns, not isolated messages. Valid signals include:
+- User correcting or rejecting the agent's approach
+- User redirecting the agent to a different mode or level of detail
+- User expressing dissatisfaction with how the agent behaved
+- User clarifying expectations that contradict the agent's behavior
+- Agent retrying a tool call with different inputs after getting poor or irrelevant results (self-correction)
+- Agent switching from one tool to another within the same task after inadequate results
+
+You MUST identify the triggering agent behavior (assumption made, default chosen, constraint ignored, or question not asked).
+
+━━━━━━━━━━━━━━━━━━━━━━
+## The Skill Test (what makes a good trigger)
+
+A valid **When** trigger must act as a **Skill Trigger** — it describes the **problem or situation**, NOT the user's explicitly stated preference.
+
+- **BAD (Topic-based):** "User talks about Python code." (Too broad)
+- **BAD (Interaction-based):** "User corrects the agent." (Too generic)
+- **BAD (Echoing preference):** "User requests CLI tools or open-source solutions." (Just restates the user's explicit ask — the agent didn't need an SOP to follow direct instructions.)
+- **GOOD (Intent-based):** "User requests help debugging a specific error trace."
+- **GOOD (Problem-based):** "User's initial high-level request is ambiguous."
+- **GOOD (Situation-based):** "User reports timeout or performance failures on large data transfers (>10TB)." (Captures the situation where the agent should default to CLI/chunking solutions.)
+
+**Tautology Check.** If the trigger can be reduced to "user asks for X" and the action is "do X", the playbook is tautological. Re-derive: What was the *problem or situation* where the agent made the wrong default choice? Use THAT as the trigger.
+
+━━━━━━━━━━━━━━━━━━━━━━
+## Reasoning procedure (required)
+
+Generate each playbook internally in the order **Why → What → When** (rationale conditions the action; both condition the trigger), but **emit** the sections in the document as **When → What → Why**:
+
+1. Identify user turns containing correction, rejection, or redirection.
+2. Trace backwards to the exact agent behavior that triggered it.
+3. Identify the violated implicit expectation — this is the seed of **Why**.
+4. Verify a confirmation signal follows within 1–2 turns. If not, abandon this candidate.
+5. Define the SOP action — this becomes **What**. Include DOs and DON'Ts only as they were actually observed in this conversation. Do not force DO/DON'T symmetry if only one side was learned; forcing symmetry leads to hallucinated pitfalls.
+6. Draft the SOP trigger — this becomes **When**. Apply the Skill Test and Tautology Check.
+7. Check that the trigger is the search anchor a future agent would retrieve on. Rewrite as a concise noun phrase describing the *situation*, not a sentence.
+8. Repeat steps 1–7 for **every distinct** behavioral issue you identified. Each independent policy becomes a separate entry in the output list.
+
+━━━━━━━━━━━━━━━━━━━━━━
+## Output format
+
+Each playbook has three body sections: `## When`, `## What`, `## Why`.
+
+- `## When` — One-sentence trigger phrase. This is the search anchor used for retrieval. Write as a noun phrase describing the *situation*, not a sentence. Apply the Skill Test.
+- `## What` — 2–3 sentences of the actual procedural rule. Include DOs and DON'Ts as they were actually observed — do not force DO/DON'T symmetry if only one was learned.
+- `## Why` — Rationale. Reference the specific correction+confirmation evidence from the transcript when helpful. Can be longer than the other sections — it is reference material, not recall content.
+
+Return a JSON array of objects. If nothing to extract, return `[]`.
+
+```json
+[
+  {
+    "topic_kebab": "commit-no-ai-attribution",
+    "when": "Composing a git commit message on this project.",
+    "what": "Write conventional, scope-prefixed messages. Do not add AI-attribution trailers like `Co-Authored-By`.",
+    "why": "On [date] the user corrected commits that included Co-Authored-By trailers. Project's git-conventions rule prohibits them. Correction stuck — the user's next request assumed the rule was internalized."
+  }
+]
+```
+
+- `topic_kebab`: kebab-case slug, ≤ 48 chars, regex `^[a-z0-9][a-z0-9-]*$`. A compression of the situation the rule applies to (e.g., `commit-no-ai-attribution`, `debug-explain-root-cause-first`, `search-specific-query-first`).
+
+━━━━━━━━━━━━━━━━━━━━━━
+## Examples
+
+**Example 1 (single entry):**
+- **Agent:** Jumps directly into code generation.
+- **User:** "Don't give me the code yet, explain the strategy first."
+- **Agent:** Outlines strategy.
+- **User:** "Good, now proceed."  ← confirmation
+
+```json
+[
+  {
+    "topic_kebab": "strategy-before-code",
+    "when": "User asks for architectural advice or complex implementation help.",
+    "what": "Outline the high-level strategy before generating code. Do not jump straight to code when the user has not explicitly asked for it.",
+    "why": "The agent assumed the user wanted code immediately, but the user needed to understand the approach first. Presenting strategy first prevents wasted effort on wrong approaches and gives the user the understanding they need to evaluate the plan."
+  }
+]
+```
+
+**Example 2 (single entry):**
+- **Agent:** Suggests `pip install …`.
+- **User:** "Stop using pip, I'm using poetry."
+- **Agent:** Reissues command as `poetry add …`.
+- **User:** "Thanks."  ← confirmation
+
+```json
+[
+  {
+    "topic_kebab": "detect-package-manager",
+    "when": "User asks for package installation commands.",
+    "what": "Detect or ask for the project's package manager preference before suggesting install commands.",
+    "why": "The agent defaulted to pip without checking the project setup, which produced commands incompatible with the user's poetry-based workflow. Detecting the package manager first avoids this whole class of mistakes."
+  }
+]
+```
+
+**Example 3 (tool input optimization via retry pattern):**
+- **Agent:** `[used tool: search_docs({"query": "error"})]` → irrelevant results.
+- **Agent:** `[used tool: search_docs({"query": "TypeError in async handler", "filter": "error_logs"})]` → relevant results.
+- **User:** "Perfect, that's the one."  ← confirmation
+
+```json
+[
+  {
+    "topic_kebab": "search-specific-query-first",
+    "when": "Agent is searching docs for a specific error or issue the user reported.",
+    "what": "Use the exact error message and relevant filters as search parameters on the first attempt.",
+    "why": "On the first attempt the agent used a vague single-word query and wasted a round-trip. The second attempt, with the exact error text and an error_logs filter, succeeded immediately. Specific queries on the first call reduce latency and cost."
+  }
+]
+```
+
+**Example 4 (avoiding tautological triggers):**
+- **User:** Reports S3 sync timeout on 12 TB backup. Agent suggests UI settings. User says "I need CLI-based automation." Agent suggests a proprietary tool. User says "I want open-source only." Agent finally suggests rclone with chunking. User: "That works."  ← confirmation
+
+- **BAD (Tautological) — do NOT emit:**
+```json
+[{"when": "User requests CLI or open-source automation tools.", "what": "Suggest CLI/open-source tools.", "why": "…"}]
+```
+This just echoes the correction. The agent doesn't need an SOP to follow explicit instructions.
+
+- **GOOD:**
+```json
+[
+  {
+    "topic_kebab": "large-transfer-cli-chunking",
+    "when": "User reports timeout or performance failure transferring large datasets (>10 TB) to cloud storage.",
+    "what": "Default to CLI-based chunking / parallel transfer solutions (e.g., rclone) and provide config snippets.",
+    "why": "The agent defaulted to GUI settings and then to a proprietary tool for a large-data transfer problem, both of which the user rejected before rclone with chunking finally worked. CLI-based chunking is the standard solution for transfers at this scale — extract the *situation* (large transfer timeout), not the user's tool preference."
+  }
+]
+```
+
+**Example 5 (multiple distinct entries from one conversation):**
+- **Conversation:** Multi-turn debugging session. (a) User asks for help fixing a `TypeError` but the agent jumps straight to code rewrites instead of explaining the root cause; after the user says "explain first", agent does so, user says "good". (b) The agent apologizes ("I'm sorry for the confusion") every time it provides a factual correction, even when no mistake occurred; user says "stop apologizing, just tell me what's correct"; agent complies; session continues.
+
+Both corrections have matching confirmations, so both become playbooks:
+
+```json
+[
+  {
+    "topic_kebab": "debug-explain-root-cause-first",
+    "when": "User asks for help debugging a specific error trace.",
+    "what": "Explain the root cause of the error before proposing any code changes. Do not jump straight to rewriting code.",
+    "why": "The user needs to understand why the error occurred in order to evaluate the fix. Skipping the explanation leaves them without the context they need and leads to repeated back-and-forth."
+  },
+  {
+    "topic_kebab": "corrections-no-unnecessary-apology",
+    "when": "Agent provides a factual correction or updated diagnosis during a multi-turn session.",
+    "what": "Deliver the correction plainly. Do not preface routine corrections with an apology when no actual mistake occurred.",
+    "why": "Apologies on every refinement eroded user confidence. Reserve apologies for genuine errors so they retain meaning."
+  }
+]
+```
+
+━━━━━━━━━━━━━━━━━━━━━━
+## Rules for output fields
+
+- The top-level response MUST be a JSON array (possibly empty).
+- Each entry MUST have `topic_kebab`, `when`, `what`, `why`. All four are REQUIRED.
+- `when` is the search anchor — keep it short, situation-focused, and Skill-Test-valid.
+- `what` captures only DOs and DON'Ts that the conversation actually evidenced. Do NOT invent a symmetric DON'T for every DO (or vice versa).
+- `why` must reference the specific agent behavior that triggered the correction AND confirm that a confirmation signal followed.
+- Each entry must describe a **distinct, independent** policy — do not split one policy across entries, and do not merge two independent policies into one.
+- If any candidate fails the confirmation gate, the Skill Test, or the Tautology Check, drop it.
+- Vague, stylistic, or unanchored advice is invalid.
+- **Never capture secrets or credentials in a playbook.** If a correction or execution trace contains API keys, tokens, passwords, or other credential material, redact that content from the `why` field before emitting the playbook. Do not emit a playbook whose `why` requires quoting credentials verbatim.
+
+## Transcript
+
+{transcript}

package/plugin/vendor/reflexio/reflexio/integrations/openclaw-embedded/plugin/prompts/profile_extraction.md

@@ -0,0 +1,132 @@
+---
+active: true
+description: "Profile extraction for Reflexio Embedded plugin (ported from profile_update_instruction_start/v1.0.0)"
+changelog: "Initial port (2026-04-16): output adapted from StructuredProfilesOutput JSON to list of {topic_kebab, content, ttl} suitable for the reflexio_write_profile tool; custom_features and metadata fields dropped; existing_profiles variable now injected from memory_search results rather than Reflexio server."
+variables:
+  - existing_profiles_context
+  - transcript
+---
+
+You extract durable user facts from conversations. Your output becomes entries under `.reflexio/profiles/`.
+
+[Goal]
+You are a user personalization learning assistant. Your job is to analyze user–agent interactions and extract **salient information about the user** that should shape how an AI agent communicates with and serves this user in future conversations.
+
+A "profile" can be:
+- **Factual information**: Direct facts about the user (name, birthday, occupation, location)
+- **Work & expertise**: Professional role, technical skills, domain knowledge, tools used daily
+- **Goals & projects**: Current objectives, ongoing projects, deadlines, milestones
+- **Life circumstances**: Living situation, health considerations, family context, time constraints
+- **Relationships & family**: Family members, pets, key people in their life
+- **Domain / environment facts**: Stable facts about the user's working environment that the agent needs to know to serve them correctly — schema details (table names, column types, units of measurement), join paths, metric definitions the user enforces, tool quirks or limitations the user works around, file-format conventions, and similar reference knowledge. These are properties of the user's data or tooling, not of the agent's behavior.
+- **Inferred personalization signals**: Patterns derived from behavior or multi-turn inference that would cause an agent to meaningfully change how it responds
+
+Profiles may be extracted from:
+- Explicit statements ("I prefer sushi")
+- Implicit signals (implied preference/acceptance/rejection)
+- Multi-turn inference (a stable pattern across multiple turns where the user never explicitly states a preference, but behavior suggests one)
+
+**Scope boundary — what is NOT a profile:**
+Profiles capture what is *true about the user or their world*. They do NOT capture
+*what the agent should do differently next time*. If a learning is a behavioral
+rule for the agent (e.g., "when the user asks about methodology, stop and propose
+a corrected plan before re-running queries", "always explain root cause before
+proposing code changes"), it belongs in the playbook extractor, not here. Extract
+only the stable facts the agent needs to know; leave the action rules to playbooks.
+
+[Your Task — Follow These Steps]
+
+STEP 1: Analyze and reason through the user interactions below and compare them to the existing profiles shown in the `{existing_profiles_context}` section.
+
+STEP 2: Decide what to extract:
+- If the interaction reveals NEW information about the user that is NOT already stored in existing profiles → Extract it as a new profile
+- If the information is already in existing profiles → Do NOT re-extract it
+- If the interaction contains NO relevant profile information → Return an empty list
+
+STEP 3: For each profile you extract, you must assign:
+- `topic_kebab`: short kebab-case slug, ≤ 48 chars, regex `^[a-z0-9][a-z0-9-]*$`. A semantic compression of the fact (e.g., `diet-vegetarian`, `role-backend-engineer`, `schema-orders-gross-cents`).
+- `content`: 1–3 sentences, one fact per entry, written as a standalone statement about the user.
+- `ttl`: one of the values from the TTL table below.
+
+[Time to Live — Choose One]
+- `infinity` → Facts that rarely change (name, birthday, gender, phone number)
+- `one_year` → Long-term preferences and slow-moving context (favorite color, hobby, long-lived schema facts)
+- `one_quarter` → Seasonal preferences or quarter-scoped projects (winter activities, holiday traditions, Q-end deadlines)
+- `one_month` → Regular preferences (food preferences, UI preferences)
+- `one_week` → Short-term or situational preferences (current project, temporary need)
+- `one_day` → Very short-lived context (today's deadline, scratch preference)
+
+[Output Format]
+Return a JSON array of objects. Each object represents one profile to write. If nothing to extract, return `[]`.
+
+```json
+[
+  {
+    "topic_kebab": "diet-vegetarian",
+    "content": "User is vegetarian — no meat or fish.",
+    "ttl": "infinity"
+  }
+]
+```
+
+[Examples With Explanations]
+
+Example 1 — Extracting a new profile:
+- Existing profiles: none related
+- Interaction: "i like to eat pizza"
+- Reasoning: User revealed a food preference. Not in existing profiles. Food preferences change monthly, so ttl is `one_month`.
+```json
+[{"topic_kebab": "food-likes-pizza", "content": "User likes pizza.", "ttl": "one_month"}]
+```
+
+Example 2 — Extracting a permanent profile:
+- Interaction: "my name is John"
+- Reasoning: User's name is a permanent fact. Use `infinity`.
+```json
+[{"topic_kebab": "name-john", "content": "User's name is John.", "ttl": "infinity"}]
+```
+
+Example 3 — Extracting work context and project:
+- Existing profiles: none
+- Interaction: "I'm a senior backend engineer at Acme Corp, currently migrating our payment service from monolith to microservices. The deadline is end of Q2."
+- Reasoning: Role is long-lived; the migration project is quarter-scoped.
+```json
+[
+  {"topic_kebab": "role-senior-backend-acme", "content": "User is a senior backend engineer at Acme Corp.", "ttl": "one_year"},
+  {"topic_kebab": "project-payments-microservices", "content": "User is migrating Acme's payment service from monolith to microservices, with an end-of-Q2 deadline.", "ttl": "one_quarter"}
+]
+```
+
+Example 4 — No relevant information:
+- Interaction: "what time is it?"
+- Reasoning: Nothing to extract.
+```json
+[]
+```
+
+Example 5 — Domain / environment fact surfaced through error correction:
+- Existing profiles: none
+- Interaction: Agent attempts `SUM(orders.total_amount)` and fails with "unknown column 'total_amount'". Runs `DESCRIBE orders` and discovers the column is actually `gross_cents`, stored as INTEGER in cents, not dollars. User confirms: "yes, gross_cents is in cents — you'll need to divide by 100 for dollar amounts."
+- Reasoning: This is a stable fact about the user's data schema (column name, type, unit). Store as a long-lived domain fact.
+```json
+[{"topic_kebab": "schema-orders-gross-cents", "content": "orders.gross_cents stores order revenue as INTEGER in cents (not dollars) — divide by 100 for dollar amounts.", "ttl": "one_year"}]
+```
+
+Note: if the same session also surfaces a behavioral rule (e.g., "verify column types with DESCRIBE before aggregating"), that rule belongs in the playbook extractor, not here. This example captures only the fact.
+
+[Important Reminders]
+1. Only extract profiles that represent salient, stable facts about the user or their world.
+2. If the information is already captured in existing profiles (see below), do NOT re-extract it.
+3. Always include `ttl` for new profiles; pick the shortest TTL that the fact will plausibly remain true for.
+4. Never output behavioral rules for the agent here — those belong to the playbook extractor.
+5. **Never extract secrets or credentials.** Do not create profile entries for API keys, access tokens, passwords, OAuth secrets, private keys, auth headers, `.env` values, connection strings, or any other credential-shaped content, even if the user pasted such content into the conversation. Treat those as noise; skip them.
+6. **Forget / delete / remove requests.** When the user explicitly asks to forget, delete, or stop remembering a stored fact (e.g. "forget that I like X", "remove my interest in Y", "don't remember that I work at Z"), emit a single profile entry whose `content` begins with "Requested removal of" and names the topic in positive form — for example, `"Requested removal of interest in self-improving agents from stored profiles"`. Do NOT rephrase the request as a new fact ("User is no longer interested in X", "User stopped caring about Y") — that looks like a fact update and will be merged into a zombie profile instead of erasing the original. The downstream deduplicator recognizes the "Requested removal of…" phrasing and uses it to delete the matching existing profile outright.
+7. Return `[]` when there is nothing new to extract.
+
+## Existing profiles for context (do NOT re-extract these)
+
+{existing_profiles_context}
+
+## Transcript
+
+{transcript}

package/plugin/vendor/reflexio/reflexio/integrations/openclaw-embedded/plugin/skills/reflexio-consolidate/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: reflexio-consolidate
+description: "Run a full-sweep consolidation over all .reflexio/ files — TTL sweep + n-way cluster merge. Use when the user asks to 'clean up reflexio', 'consolidate memory', 'deduplicate playbooks', or suspects drift across sessions."
+---
+
+# Reflexio Consolidate
+
+User-invocable via `/skill reflexio-consolidate`. Same workflow that runs automatically via heartbeat (every 24h of active use), but on-demand.
+
+## What it does
+
+1. TTL sweep: delete expired profile files.
+2. For each of profiles and playbooks:
+   - Cluster similar files via `memory_search`.
+   - For clusters of 2+ members, call `llm-task` with `prompts/full_consolidation.md` to decide consolidate (one-fact-per-file) or keep-all.
+   - Apply decisions: write individual fact files, delete originals.
+
+## How to run
+
+Call the `reflexio_run_consolidation` tool. It spawns the consolidator sub-agent and returns a `runId`.
+
+After successful consolidation, call the `reflexio_consolidation_mark_done` tool to update the heartbeat timer.
+
+## When to use
+
+- User asks to "consolidate", "clean up reflexio", "dedupe memory"
+- User reports seeing duplicate or contradictory entries in retrieval
+- Heartbeat check returns ALERT (automatic trigger)
+
+## When NOT to use
+
+- Routine maintenance — heartbeat handles this automatically.
+- Immediately after Flow A/B writes — shallow dedup at write time + Flow C at session end cover the fresh-extraction cases.

package/plugin/vendor/reflexio/reflexio/integrations/openclaw-embedded/plugin/skills/reflexio-embedded/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: reflexio-embedded
+description: "Captures user facts and procedural corrections into .reflexio/ so the agent learns across sessions. Use when: (1) user states a preference, fact, config, or constraint; (2) user corrects the agent and confirms the fix with an explicit 'good'/'perfect' or by moving on without re-correcting for 1-2 turns; (3) at start of a user turn, to retrieve relevant facts and playbooks from past sessions."
+metadata:
+---
+
+# Reflexio Embedded Skill
+
+Captures user facts (profiles) and procedural corrections (playbooks) into `.reflexio/`, so the agent learns across sessions. All memory lives in Openclaw's native primitives — no external service required.
+
+## First-time setup per agent
+
+If `.reflexio/.setup_complete_<agentId>` does NOT exist (where `<agentId>` is your current agent id), perform this one-time check. The setup step runs probing commands via `exec` and asks for approval before making changes.
+
+**Steps:**
+
+1. Probe current config:
+   - `openclaw config get plugins.entries.active-memory.config.agents`
+   - `openclaw config get agents.defaults.memorySearch.extraPaths`
+   - `openclaw memory status --deep`
+
+2. If active-memory is not targeting this agent:
+   Ask user: *"To auto-inject relevant facts into each turn, I can enable active-memory for this agent. OK if I run `openclaw config set plugins.entries.active-memory.config.agents '[\"<agentId>\"]' --strict-json`?"*
+   On approval, run the command.
+
+3. If `.reflexio/` is not registered as an extraPath:
+   Ask user: *"I need to register .reflexio/ as a memory path. OK if I run `openclaw config set agents.defaults.memorySearch.extraPaths '[\".reflexio/\"]' --strict-json`?"*
+   On approval, run the command.
+
+4. If no embedding provider is configured (FTS-only mode):
+   Tell user: *"Vector search requires an embedding API key (OpenAI, Gemini, Voyage, or Mistral). The plugin works without one but retrieval quality drops. Would you like guidance on adding one?"*
+   If yes, guide them through `openclaw config set` or `openclaw configure`.
+
+5. On each decline, note the degraded mode but do not block:
+   - No active-memory → you must run `openclaw memory search` via exec at turn start (see "Retrieval" section below).
+   - No extraPath → WARN the user the plugin cannot function without this step.
+   - No embedding → continue with FTS-only.
+
+6. When all checks resolved (approved or accepted with warning): create the marker:
+   ```bash
+   mkdir -p .reflexio
+   touch .reflexio/.setup_complete_<agentId>
+   ```
+
+**If exec is not available** (strict admin policy): fall back to telling the user the exact commands to run manually.
+
+## First-Use Initialisation
+
+Before any write, ensure `.reflexio/` and its subdirectories exist. This is idempotent — safe to run every session:
+
+```bash
+mkdir -p .reflexio/profiles .reflexio/playbooks
+```
+
+Never overwrite existing files. Never write secrets, tokens, private keys, environment variables, or credentials into `.reflexio/` files. When capturing a fact involves a user-pasted snippet that contains credentials, redact first.
+
+## Quick Reference
+
+| Situation                                                 | Action                                     |
+|-----------------------------------------------------------|--------------------------------------------|
+| User states preference, fact, config, or constraint       | `reflexio_write_profile` tool              |
+| User correction → you adjust → user confirms              | `reflexio_write_playbook` tool             |
+| Start of user turn, need context                          | `reflexio_search` tool                     |
+| Unsure whether to capture                                 | Skip; batch pass at session-end has a second shot |
+
+## Detection Triggers
+
+### Profile signals (write immediately, same turn)
+
+- **Preferences**: "I prefer X", "I like Y", "I don't like Z", "I always do Q"
+- **Facts about self**: "I'm a [role]", "my timezone is X", "I've been doing Y for Z years"
+- **Config**: "use X", "our team uses Y", "the repo is at Z"
+- **Constraints**: "I'm vegetarian", "no dairy", "I can't X", "don't use Y"
+
+For each such signal, call the `reflexio_write_profile` tool with a kebab-case topic slug and an appropriate TTL. See "TTL Selection" below.
+
+### Playbook signals (write AFTER confirmation)
+
+Playbooks require a specific multi-turn pattern:
+
+1. **Correction**: *"No, that's wrong"*, *"Actually..."*, *"Don't do X"*, *"Not like that"*, *"We don't use X here"*.
+2. **You adjust**: you redo the work per the correction.
+3. **Confirmation** (required — without this, do NOT write a playbook):
+   - Explicit: *"good"*, *"perfect"*, *"yes that's right"*, *"correct"*.
+   - Implicit: the user moves to an unrelated topic without re-correcting for 1-2 more turns.
+
+**Explicit don't-write rule**: if you see a correction without subsequent confirmation, do not write a playbook. The fix may be wrong; let the batch pass at session end re-evaluate.
+
+## Retrieval
+
+### When Active Memory is enabled
+
+Your turn context may already contain Reflexio-prefixed entries injected by Active Memory. Incorporate them before responding. No tool call needed.
+
+### Fallback when Active Memory is absent
+
+At the start of each user turn, call the `reflexio_search` tool with:
+- query: "<user's message>"
+
+The tool handles query preprocessing and memory search internally.
+Incorporate any results into your response. Skip if the user's message is trivial.
+
+**Important:** Do NOT use the `memory_search` tool (returns config, not results)
+or `exec` with `openclaw memory search` — use the `reflexio_search` tool instead.
+
+## File Format
+
+**Do NOT construct filenames or frontmatter by hand.** Use the registered tools (`reflexio_write_profile`, `reflexio_write_playbook`). They generate IDs, enforce the frontmatter schema, and write atomically.
+
+### Profile template (for mental model — the script emits this)
+
+```markdown
+---
+type: profile
+id: prof_<nanoid>
+created: <ISO timestamp>
+ttl: <enum>
+expires: <ISO date or "never">
+supersedes: [<old_id>]   # optional, only after a merge
+---
+
+<1-3 sentences, one fact per file>
+```
+
+### Playbook template
+
+```markdown
+---
+type: playbook
+id: pbk_<nanoid>
+created: <ISO timestamp>
+supersedes: [<old_id>]   # optional
+---
+
+## When
+<1-sentence trigger — this is the search anchor; make it a noun phrase>
+
+## What
+<2-3 sentences of the procedural rule; DO / DON'T as actually observed>
+
+## Why
+<rationale, can be longer — reference only, not recall content>
+```
+
+### How to invoke
+
+**Profile:** Call the `reflexio_write_profile` tool with:
+- slug: "diet-vegan"
+- ttl: "infinity"
+- body: "User is vegan. No meat, no fish, no dairy, no eggs."
+
+**Playbook:** Call the `reflexio_write_playbook` tool with:
+- slug: "commit-no-ai-attribution"
+- body: "## When\nComposing a git commit message.\n\n## What\nNo AI-attribution trailers.\n\n## Why\nUser corrected this."
+
+**Retrieve context:** Call the `reflexio_search` tool with:
+- query: "user's question here"
+
+All tools handle preprocessing, memory search, contradiction detection, and file operations internally. You only detect the signal, compose the content, and call the tool.
+
+## TTL Selection (profiles only)
+
+- `infinity` — durable, non-perishable facts (diet, name, permanent preferences)
+- `one_year` — stable but could plausibly change (address, role, team)
+- `one_quarter` — current focus (active project, sprint theme)
+- `one_month` — short-term context
+- `one_week` / `one_day` — transient (today's agenda, this week's priorities)
+
+Pick the most generous TTL that still reflects reality. When in doubt, prefer `infinity` — let dedup handle later contradictions via supersession.
+
+## Safety
+
+- **Never write secrets.** No API keys, tokens, access tokens, private keys, environment variables, OAuth secrets, auth headers. If the user's message contains any of these, redact them before writing.
+- **Redact pasted code.** User-pasted snippets often contain credentials. Strip them first.
+- **PII.** Do not capture PII beyond what's operationally useful (name, timezone, role are fine; government IDs, addresses, phone numbers only if explicitly relevant).
+
+## Best Practices
+
+1. **Write immediately** on a clear signal. Don't queue to session-end — that's Flow C's job; you have a different role.
+2. **One fact per profile file.** Multi-fact files are harder to dedupe and easier to contradict.
+3. **Trigger phrase = search anchor.** Write `## When` as a noun phrase describing the situation, not a sentence. Retrieval hits on semantic similarity to this field.
+4. **Skip writing when uncertain.** Flow C has a second pass over the full transcript. It's better to let it handle ambiguous cases.
+5. **Prefer shorter TTL for transient facts.** Don't let "working on project X" accumulate as infinity-TTL cruft.
+
+## Opt-in Hook
+
+This skill works standalone — your in-session Flow A (profile) and Flow B (playbook) writes populate `.reflexio/` without any hook.
+
+The optional hook (`hook/` directory of this plugin) adds two capabilities:
+
+1. **TTL sweep at session start**: deletes expired profiles before Active Memory runs.
+2. **Session-end batch extraction (Flow C)**: on `session:compact:before`, `command:stop`, or `command:reset`, spawns a `reflexio-extractor` sub-agent that extracts profiles/playbooks from the full transcript and runs shallow pairwise dedup.
+
+See this plugin's `README.md` for install instructions (runs via `./scripts/install.sh`). If the hook is not installed, Flows A+B still work.

package/plugin/vendor/reflexio/reflexio/integrations/openclaw-embedded/references/HOOK.md

@@ -0,0 +1,18 @@
+---
+name: reflexio-embedded
+description: "Reflexio Embedded hook: TTL sweep on bootstrap; spawn reflexio-extractor sub-agent at session boundaries."
+metadata:
+  openclaw:
+    emoji: "🧠"
+    events:
+      - "before_agent_start"
+      - "before_compaction"
+      - "before_reset"
+      - "session_end"
+---
+
+> **Note:** This file is no longer discovered by the Openclaw CLI. Hooks are
+> now registered programmatically from `../index.ts` via
+> `definePluginEntry({ register(api) { api.on(...) } })`. This doc is kept
+> only for human reference; see `../index.ts` and `./handler.ts` for the
+> actual behaviour.

package/plugin/vendor/reflexio/reflexio/integrations/openclaw-embedded/references/architecture.md

@@ -0,0 +1,49 @@
+# Architecture
+
+Deep-dive for maintainers. For a design-level overview, see the spec at
+`docs/superpowers/specs/2026-04-16-reflexio-openclaw-embedded-plugin-design.md`.
+
+## Three flows
+
+| Flow | Trigger | Actor | Purpose |
+|------|---------|-------|---------|
+| A | User message signals a profile | Main agent (skill-guided) | Capture durable user facts mid-turn |
+| B | Correction → adjust → confirmation | Main agent (skill-guided) | Capture procedural rules after confirmation |
+| C | `session:compact:before`, `command:stop`, `command:reset` | `reflexio-extractor` sub-agent spawned via hook | Batch extract + shallow dedup over full transcript |
+| Cron | Daily 3am | `reflexio-consolidator` sub-agent | Full n-way consolidation + TTL sweep |
+
+## File system invariants
+
+- `.reflexio/profiles/*.md` and `.reflexio/playbooks/*.md` — the only user-owned data.
+- All files are **immutable in place**. Dedup = delete old + create new (atomic via `.tmp` + rename).
+- Every file has frontmatter with `type`, `id`, `created`. Profiles also have `ttl` and `expires`.
+- `supersedes: [id1, id2]` — optional, records merge lineage.
+
+## Concurrency model
+
+- Flow A + Flow B are create-only; no coordination.
+- Flow C runs as a sub-agent spawned via `api.runtime.subagent.run()` — non-blocking, tracked by Openclaw's Background Tasks ledger.
+- Parallel Flow C runs can occur; rare race resolves next cycle (later write wins, orphans swept by full consolidation).
+
+## Openclaw primitives leveraged
+
+- **Memory engine** (`concepts/memory-builtin`): indexes `.md` files under `extraPaths`.
+- **Active Memory** (`concepts/active-memory`): optional, injects retrieved context into turns.
+- **Hooks** (`automation/hooks`): lifecycle events (bootstrap, compact, stop, reset).
+- **Sub-agents** (`tools/subagents`): fire-and-forget work via `sessions_spawn` / `api.runtime.subagent.run()`.
+- **LLM-task** (`tools/llm-task`): structured LLM calls with schema validation.
+- **Cron** (`automation/cron-jobs`): daily consolidation.
+- **Registered tools**: `reflexio_write_profile`, `reflexio_write_playbook`, and `reflexio_search` — the plugin's tool-based interface for writes and retrieval.
+
+## Prompt loading
+
+Prompts live in `prompts/` and are loaded at runtime by sub-agents. Frontmatter follows Reflexio's prompt_bank convention (`active`, `description`, `changelog`, `variables`). When the sub-agent builds a `llm-task` call, it reads the relevant prompt file, substitutes variables from the event / memory_search results / candidate data, and sends the result to `llm-task` with an output schema.
+
+## Graceful degradation
+
+| Missing prereq | Behavior |
+|---|---|
+| `active-memory` not enabled | SKILL.md instructs agent to run `memory_search` fallback at turn start |
+| No embedding provider | Falls back to FTS/BM25 only; vector search unavailable but plugin functional |
+| Registered tools unavailable | SKILL.md falls back to printed manual commands; install.sh exits with instructions |
+| No `openclaw cron add` | install.sh prints warning; consolidation runs only on `/skill reflexio-consolidate` |