Reflexio

Captures user facts and procedural corrections into .reflexio/ so the agent learns across sessions. Use when: (1) user states a preference, fact, config, or...

Security Scan

The skill's files and runtime instructions are coherent with its stated purpose (local, Openclaw-based capture of user facts and playbooks); it asks for local config tweaks and uses LLM-driven prompts to read/merge/write .reflexio files but does not request unrelated credentials or remote downloads.

Purpose & Capability

Name/description (capture profiles/playbooks into .reflexio/) align with the code and prompts: tools for extracting, deduping, writing, consolidating, and searching memories are present. The plugin asks to register .reflexio/ as a memory path and to enable active-memory for better retrieval — these are expected for the stated purpose.

Instruction Scope

SKILL.md instructs the agent (with user approval) to run `openclaw config set` commands and to create a `.reflexio/.setup_complete_<agentId>` marker; it also instructs LLM-driven extraction and to call local tools (reflexio_search/write_*) and run `openclaw memory search` via an injected runner. These actions are within scope but have side effects on agent config and local files; the skill explicitly warns to never write secrets but this is a policy requirement (not fully enforced by code).

Install Mechanism

No external install/download URLs are used. The plugin ships as source files (TypeScript) intended to be installed via Openclaw CLI; there is no bake-in network fetch or archive extraction from an untrusted host in the manifest.

Credentials

The skill declares no required env vars or credentials. It optionally suggests configuring an embedding provider for improved retrieval quality (user-supplied API key); that is reasonable and optional. The code reads WORKSPACE if present (standard) and relies on platform-provided inferFn/runner rather than requiring extra secrets.

Persistence & Privilege

always:false. The skill may propose changing global Openclaw plugin/config settings (active-memory agents list and agents.defaults.memorySearch.extraPaths) — it asks for explicit approval before making changes. Allowing those changes will affect how memory is injected globally for agents; this is expected but significant, so approve only if you accept those side effects.

Scan Findings in Context

[system-prompt-override] expected: The prompt templates and LLM-directed JSON outputs embedded in the repo triggered a 'system-prompt-override' pattern. This is expected for a plugin that uses LLM prompts to rewrite/deduplicate content, but you should still review the prompt text because prompts that instruct model behavior are the real control surface for what gets written.

Assessment

This plugin appears to do what it says: it extracts and stores local user facts and playbooks under .reflexio/ and uses Openclaw's memory/LLM capabilities to dedupe and consolidate. Before installing: (1) review the code and prompt templates if you don't trust their behavior, especially the LLM prompts that produce JSON used to write/delete files; (2) run it in a safe/test workspace first (backup or isolate any existing .reflexio/); (3) decline the automated config changes if you don't want the plugin to alter global active-memory or memorySearch.extraPaths (you can perform the steps manually after review); (4) do not paste secrets into conversations — the skill instructs redaction but relies on agent behavior to obey that rule; (5) if you require stricter controls, disable exec/automatic config changes and perform setup steps manually. Overall the package is internally coherent, but it has privileges to change Openclaw config and to write/delete local files — grant those only when you trust the plugin and have reviewed the prompts and code.

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:

   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:

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)

---
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

---
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.