Pi × EvoX Loop — Agent Experience Inheritance Skill

What does Pi × EvoX Loop — Agent Experience Inheritance Skill do?

Let every pitfall be encountered only once per agent: failed experiences are automatically stored (guard-filtered), and verified fixes for similar tasks are recalled automatically.

Terminology convention (0.29): The main text uses English; technical fields are noted with the original English term in parentheses on first occurrence (e.g., "signal matching signals_match"), and thereafter consistently use English. For a complete Chinese-English glossary, see docs/faq.md Q17.

Document map (0.21 layered):

• New users only need to read three sections: 30-second quick start → Flow A → Flow B (about 60 lines); the rest as needed.
• One-minute decision guide: docs/one-pager.md (new in 0.30)
• Best practices central hub: examples/quickstart.md (5-minute closed loop) + docs/overview.md (project overview) + docs/common-mistakes.md (14 anti-patterns) — three documents covering "start/overview/avoid traps".
• The rest of this file = triggers/safety summary/anti-pattern quick reference/navigation; docs/advanced.md = backfill addressing/timeline/harvest/concurrency lock/shared pool/host integration/operations/security gate details; docs/common-mistakes.md = complete list of common usage errors; docs/config-errors.md = common configuration errors; docs/faq.md = complete FAQ.
• docs/research.md = Flow C controlled experiments + trap design discipline — research-only, most users need not open it.

30-Second Quick Start

EN: Requires Node >= 22. Optional @evomap/evolver integration is GPL-3.0-or-later (only if you install and use --engine evolver); the default light backend is MIT, zero-dependency, zero-exfiltration. Three things only: A recall validated fixes at task start, B deposit after fixing a non-obvious failure, C (optional, research) controlled experiments. Daily use = A/B only. ⚠️ Prerequisite: Node ≥ 22 (check with node -v; older versions are not supported and must be upgraded first). Optional @evomap/evolver integration is GPL-3.0-or-later — only relevant if you actively install and use --engine evolver; the default light backend is MIT, zero-dependency, zero-exfiltration.

This Skill does only three things: A recall validated fixes at task start, B deposit after fixing a non-obvious failure, C (optional, research) quantify benefits with controlled experiments. Daily use only A/B; C is fully off by default. Do not use C in production.

# A — At task start, targeted recall (replace with your task description)
node code/evolver-recall.mjs --query "Handle GBK encoded file errors" --top 5

# B — After fixing a non-obvious failure, paste the original error, generate a draft, then commit FIX to store
node code/light-cli.mjs draft --error "<original error>" --tool <tool name> --context "<what you were doing>"
node code/light-cli.mjs draft --error "<original error>" --strategy "AVOID: <what NOT to do> FIX: <specific parameters/commands/encoding>" --commit

All commands should be executed from the repository root; if dependencies are not installed, see the "Installation" section below.

First Run · 3 Steps to Ready (Self-Check First, Then Deposit)

1. Install Node ≥ 22 (required by traps generator and pi/evolver; see FAQ·Q8);
2. Self-check environment: node code/light-cli.mjs doctor — validates Node version, experience store directory writability, and hit registration directory reachability (provides guidance for failures);
3. Light up the experience store: An empty store with no recallable fixes is normal. Deposit the first fix using Flow B below to light it up.

Newcomer Essentials (Quick FAQ Overview)

• First run recall shows "No recallable fixes"? Normal — the store starts empty; run Flow B once to deposit and light it up (FAQ·Q1).
• Node version requirement? Must be ≥ 22 (traps generator also needs Python 3); too low and pi/evolver will fail to start (FAQ·Q8).
• More questions in docs/faq.md (complete 14 entries) and the anti-pattern quick reference below.

Installation (One-Time)

EN: One-time setup. A/B flows need ONLY Node >= 22 — zero npm dependencies. Get the folder by any of three paths below; any location works (a "skill" is just a folder — put it wherever your host expects, e.g. ~/.claude/skills/pi-evox-lab). Default backend = built-in light (pure Node, MIT). evolver is an optional integration (--engine evolver, needs npm install). Flow C additionally needs Pi CLI + an OpenAI-compatible LLM key.

Three ways to obtain (choose any):

# Path 1: git clone (recommended)
git clone https://github.com/stwhwing/pi-evox-lab.git && cd pi-evox-lab
# Path 2: Restricted network → Download Release zip (with sha256), extract and use
#   https://github.com/stwhwing/pi-evox-lab/releases (domestic accessible mirrors in FAQ Q7)
# Path 3: One-click marketplace install — search pi-evox-loop on skillhub.cn / ClawHub (for WorkBuddy/OpenClaw users)

node -v                # Prerequisite: Node >= 22 (the only hard dependency)
node code/light-cli.mjs doctor   # 30-second self-check — if passed, it's ready, no install steps needed

• A/B daily flow has zero npm dependencies; the following npm install is only for optional integration/experimental mode C:

Provider Configuration (Only for Flow C)

EN: Flow C only - any OpenAI-compatible endpoint; $ENV interpolation needs pi >= 0.85.1. Examples + domestic endpoints (DeepSeek/Bailian/SiliconFlow/Zhipu): docs/providers.md.

Flow A: At Task Start — Recall Experience (Any Non-Trivial Task)

EN: Flow A - recall at task start. --query with the task text does targeted recall (unrelated experience is never injected - injection is gated by signals_match x query-token overlap, below threshold = no injection). On error (T3), the raw error text IS the query. Multiple matches: geneConflicts drops anti_patterns-mutual low scorers; no targeted hit = no injection. Register the hit at task end with --register-hit --gene <id> (id-addressed, concurrency-safe).

# Common domestic scenario (Chinese Windows logs / CSV default GBK, reading as utf-8 will fail) — after running starter with an empty store, try this first for best effect
node code/evolver-recall.mjs --query "Reading Chinese logs encounters UnicodeDecodeError" --top 5

# Recommended: use task text for targeted recall (experience irrelevant to the task will not be injected)
node code/evolver-recall.mjs --query "<a one-line description/key signal of the current task>" --top 5

# When encountering an error (T3): the original error text is the query — the error itself is the reminder
node code/evolver-recall.mjs --error "UnicodeDecodeError: 'utf-8' codec can't decode byte 0xc4"

• Outputs only a list of gene IDs that are audited AND passed the fix guard AND targeted to the query (an empty store gives a clear prompt, which is normal);
• Default parameters: --top defaults to 5 entries (soft prompt injection has context cost; less is better); the experience store has no hard capacity limit, but it's recommended to keep a single store below 500 entries (above which targeting accuracy decreases; use a shared pool to distribute);
• Targeting rule: scored by intersection of gene signals_match hits and query tokens; below threshold, the entire entry is not injected (avoiding non-targeted injection which increases costs);
• Multi-gene conflicts: the geneConflicts guard automatically removes anti_patterns mutually exclusive low-scoring items; if multiple remain, take the highest scorer; if no targeted item exists, it's better not to inject rather than using irrelevant genes;
• When relevant to the task, prioritize its use; at task end, if a particular gene was actually used, register a hit (--gene <id> addressed by id, concurrency-safe):

node code/evolver-recall.mjs --register-hit --gene <asset_id or gene_id> --note "<one-line task description>"

• Do not force irrelevant experience; unadopted entries need not be registered.

Flow B: After Fixing a Failure — Deposit Experience

EN: Flow B - deposit after fixing a non-obvious failure. Deposit bar (any one): docs/2+ tries needed, environment-specific, counter-intuitive error, or second occurrence. Guided path: draft --error auto-extracts signals + pre-fills AVOID + writes anti_patterns; fill in FIX then --commit. Manual path: distill with explicit signals. strategy MUST be an executable fix (params/commands/encodings) - success summaries are filtered by the repair-signal guard. --shareable only for genes meant for the shared pool. Deposit criteria (any one qualifies):

• Troubleshooting required checking documentation / trial and error ≥ 2 times to resolve;
• Depends on machine or environment characteristics (encoding, path conventions, shell differences, network environment);
• Error message is counter-intuitive or inconsistent with documentation;
• The same pitfall has appeared a second time in historical tasks. (If none of the criteria are met, a normal failure need not be deposited — to avoid noise in the experience store.)

Recommended path: Guided (paste original error; signals and "negative experience" are automatically extracted)

# 1) Generate draft: auto-extract signals_match + pre-fill AVOID template + write anti_patterns (negative experience tokens)
node code/light-cli.mjs draft --error "<original error text>" --tool <tool name> --context "<what you were doing>"

# 2) Complete FIX according to the draft, then deposit (--strategy overrides pre-filled placeholders)
node code/light-cli.mjs draft --error "<original error text>" \
    --strategy "AVOID: <what NOT to do> FIX: <specific parameters/commands/encoding>" --commit

# 3) Audit (four-state state machine — see the 'Audit State Machine' section below; approve automatically runs evidence collection first)
node code/light-cli.mjs approve <gene_id>

AVOID/FIX template boundaries (write clearly to avoid guard rejection):

Section	What to Write	Boundary
AVOID:	What NOT to do (negative experience, may contain dangerous words — those are warnings)	One to two sentences; do not write success summaries
FIX:	Executable fix specific to parameters/commands/encoding	Must be genuinely filled — placeholders/retry logs/narrations will be rejected by the depositionGate (fail-closed)
anti_patterns:	Single token literal (e.g., assume-default-utf8)	Conflict determination matches the entire string; do not write kebab-case long phrases
signals_match:	Recall targeting signal words	Only recallable if there's overlap with the query words; do not stack irrelevant words

Alternative path: Manual (when signals are already clear)

node code/light-cli.mjs distill --category repair --signals bash,exception \
    --strategy "<one-line fix; multiple steps separated by semicolons; must be specific to parameters/commands/encoding>" \
    --summary "<one-line description of the pitfall>" [--shareable]

• strategy must be written as an executable fix (including specific parameters/commands), do not write success summaries — the recall side has a fix guard that will filter out success summaries (quality over quantity);
• --shareable only when you want the gene to enter the shared pool (default not shared = no external transmission);
• Deposit threshold's real data (honest boundaries): The density of "clean fix pairs" that can be automatically extracted in real production sessions is very low (measured distillablePairs=0) — the library's genes mainly come from manual/guided deposits.

Deposit Quality Gate depositionGate (0.17.0, fail-closed)

EN: Quality gate at DEPOSITION time (fail-closed): rejects unfilled placeholder / retry-log repetition / narration openings / missing repair-signal words / AVOID-without-FIX. Non-interactive deposits default to quarantined. Full review semantics: the「Audit State Machine」section below. On distill / draft --commit, each entry is checked; invalid entries are directly rejected (not written to disk):

Rejection Condition	Reason	Next Step
FIX is an unfilled placeholder <fill in executable fix here>	Useless after injection	Fill in the real fix in the draft and re-submit
retry with corrected args (retry log paraphrase)	"Retried and it worked" is not a fix	Write AVOID (why wrong) + FIX (how to do it)
Narration opening (Now I understand…)	Reasoning stream is not executable	Same as above
Missing fix signal words	Does not describe a pitfall and fix	Same as above
Has AVOID but no FIX (half-baked)	Only pitfall without fix; useless after injection (0.22 review evidence: all 3 truncated deposits were this form)	Add executable fix (parameters/commands/encoding)

Audit State Machine (Single Source of Truth · 0.36 Convergence)

All audit semantics from gene entry to injectability are maintained only in this section; all other documents point here (preventing multiple statement drift — called out in 0.35 evaluation). EN: The single source of truth for all review semantics; other docs only point here.

Scenario	Default Behavior	Override Method
Local interactive deposit (draft --commit / distill, with TTY)	Auto-approved	config --auto-approve off to switch to manual; only affects local deposits
Local non-interactive deposit (script/cron/pipe, no TTY)	Default quarantined	Explicit --auto-approve to pass
approve <gene_id>	Auto-runs evidence first — local four ledgers (tool errors/recall/injection/backfill) three-level output (strong evidence/weak context/no evidence); approve only if consistent	--skip-evidence is an explicit emergency exit for known no-evidence scenarios (not encouraged); keep quarantined and logged if conclusions overturned by later events
Pool import gene import / gene pull	official tier direct pass (signature verification); community default quarantined	Determined by --tier

• Why approve is tied to evidence: In 0.20.3, the evidence command was created but relied on "remembering to run it" — all 6 reviews that day bypassed evidence collection. The mechanism must be bound to the action node (T3 philosophy: the error itself is the reminder).
• The status ledger review.jsonl is LWW append-only; approve/quarantine are bidirectional reversible; "pending" in info means the last state is neither approved nor quarantined.
• Relationship with the two quality gates: depositionGate rejects before entry (previous section), the four guards filter on the recall side (next section) — rejection by either layer means no injection.
• Genes without local evidence (shared pool/other machines/starter pack source) are audited based on content and source, with a note at approval.

EN: Review-with-evidence (0.20.3): before approve, run evidence <gene_id> to check the four local ledgers for events matching the gene's claimed failure/fix. Approve only when consistent; genes whose conclusions were overturned by later events stay quarantined with an audit note. Genes without local evidence (pool imports / other machines / starter pack) are reviewed on content and source, noted at approval.

Gene Signature and Provenance (0.21)

EN: Every deposit is signed with this machine's Ed25519 identity (private key 0600, never leaves the machine); pool imports verify signatures - tampered content is REJECTED. Version-by-version details (v2 canonicalization, source attribution, source_kv, decay): docs/advanced.md §Provenance.

• Deposit auto-signs, embedded when entering the pool, signature verified on import: content tampered → import rejected; unsigned older genes are accepted as-is (legacy);
• Private key never leaves the machine; public key accompanies genes in/out of the pool for verification by other machines — the trust model is "trace by keyid", not a centralized CA;
• Provenance fields are automatically recorded with deposit/backfill (source_model / source_host / source_kv compression scheme family); gene validity decays based on feedback (90-day time half-life + negative pressure, floor 0.25, no feedback = no decay) — version-by-version details (v2 canonicalization / precise attribution / phase logging / decay parameters) in docs/advanced.md §Provenance.

Deployment and Distribution (0.23)

EN: Download paths, host integration, pool collaboration, concurrency semantics and scoring; version-by-version detail in docs/advanced.md §Deployment.

• Download: GitHub Release zip / npm (domestic mirrors in FAQ Q7, sha256 included for verification);
• Host integration: light-cli.mjs install <claude-code|cursor|codex|agents-md> (--yes to write to disk); for OpenClaw/Hermes, use install-hooks; trigger rules can be written into any instruction file via install-snippet;
• Gene pool collaboration: gene pull --pool <URL|name> --tier official [--scene <scene>] (signature verification); gene submit --bundle <file> to return to maintainer; named pools in ~/.evomap/pools.json; contribution terms in CONTRIBUTING.md (CC-BY-4.0);
• Concurrency semantics (three layers, full behavior table in docs/boundary-and-triggers.md §5): single-machine multi-session = withLock file lock; cross-machine = gene pool with Git (LWW ledger arbitration); multi-host addressed by gene_id (since 0.18);
• Recall scoring and thresholds (public values): signal hit +3 each + query body token overlap +1 each + load balancing bias ±2; below threshold of 2 points, not injected (non-targeted injection is worse than no injection, measured +36pp); tokenization = ASCII tokens (≥3 characters) + Chinese 2-character bigrams — multi-character Chinese phrases in signals are invalid (fix-signals can check);
• Session fencing (0.27): session open "<task>" completes T1 recall + accounting in one step; session close "<conclusion>" finalizes — unpaired open/close will be rejected by the build gate (audit bound);
• Effect quantification and backfill: report weekly report (L1 activity/L2 backfill rate/L3 recurrence, --json machine-readable); recall --record "<conclusion>" backfill verification conclusion; license verify <token> verify Ed25519 signature license;
• IO resilience and error codes (0.34): Transient errors auto-retry (3 times, 3s interval) → circuit breaker after 5 consecutive failures for 10s (closes when IO recovers); all failures include named error codes [E_USAGE]/[E_ARGS]/[E_GUARD]/[E_NOTFOUND]/[E_INTERNAL] (preserving exit codes 0/1/2) — parameters and full table in docs/advanced.md;
• Theoretical origin: The problem awareness of heterogeneous verification comes from arXiv:2512.05117 (see README acknowledgments and docs/research.md for details); version-by-version details (provenance/alias trigger words/license/decay parameters) in docs/advanced.md §Deployment.

Security: Four Gates (0.16.0)

EN: Four gates: repair-signal guard, narration guard, injection guard (malice; AVOID=warning allowed vs FIX=instruction blocked), redaction gate (privacy, fail-closed off-machine). Per-gate details: docs/security-and-license.md §Gates.

#	Gate	What it Checks	Where it Applies
1	Fix Guard	Is there a real fix? (no executable content → no injection; quality over quantity)	Recall
2	Narration Guard	Is it a narration stream? (narration is zero information to agents, measured +36pp noise)	Recall
3	Injection Guard	Is it a malicious instruction? (prompt injection → no injection; main defense against "gene reverse control of host")	Recall (CLI / Pi extension bridge simplified version / orchestrator) + Import + Export
4	Redaction Gate	Does it leak private content? (IP/path/keys → block outbound)	Export + Import

• Degradation semantics: Export/Import fail-closed (guard module missing = execution rejected); recall side only skips the injection gate, the other three gates operate normally (host bootstrap path should not be blocked by guard failures for the user — read-only is not blocked, writes must be closed).
• What each gate specifically scans, behavior upon hit, two missed detections fixed in 0.31 and regression test cases: all in docs/security-and-license.md §Gates — this document does not repeat injection trigger characteristics to avoid being used as a sample by scanners (this repo has a precedent of releasing a version for this reason).

Capability Boundaries Quick Reference (When Not to Expect It)

6 categories of non-applicable scenarios (multiple machines writing to a single library / 100% pitfall avoidance guarantee / real-time synchronized library / one-time tasks / as an authoritative knowledge base / direct reuse across architectures) and quantitative boundaries (default injection 5 entries, library size limit not measured, no cross-machine distributed lock, Node ≥22) all in docs/boundary-and-triggers.md §1–§2. EN: Capability limits ("when NOT to use") and quantitative bounds: docs/boundary-and-triggers.md §1–§2.

When to Remind: Five Trigger Points (Core Design of 0.16.0)

EN: Recall bound to concrete action nodes, never left to memory: T1 task start, T2 before first side-effecting action, T3 on error (the error text IS the query), T4 after fixing, T5 task end (register-hit/negate). Full spec: docs/boundary-and-triggers.md. "Skill installed but no one calls it" is the most fundamental failure mode of this project — even the author forgets (measured: relevant genes can rank #1 in recall, yet the same pitfall is repeated because recall was not run before acting). Therefore, we cannot rely on users to remember; recall must be bound to concrete action nodes.

#	Trigger Point	Timing	Command	What Happens If Missed
T1	Task Start	When receiving a non-trivial task, before planning	recall --query "<task>"	Preventive failure: the avoidable pitfall is hit again
T2	Before Action	Just before the first irreversible action (writing a file/committing code/deploying/calling an external API/deleting or modifying data); for similar actions within the same task, trigger only once, subsequent actions use the same conclusion	Same as above (query = the specific action about to be performed, e.g., "batch modify files with a script")	Close-proximity prevention (optional)
T3	Encountering an Error	Tool returns an error, before preparing a retry	recall --error "<original error text>"	Most regrettable: the fix is already in the store, yet the agent blindly retries
T4	After Fixing a Pitfall	When a non-obvious pitfall has been fixed	draft --error ... (deposit)	Experience is lost; the next machine will hit the same pitfall
T5	Task End	Finalization	--register-hit --gene <id> / --negate --gene <id>	Cannot measure; invalid fixes are never discovered

T3 highlighted separately (highest benefit, yet most easily overlooked): The only trigger point where "you don't need to remember" — the error itself is the reminder. When a tool returns an error, before preparing a retry, use the original error text directly as the query (don't summarize it yourself): node code/evolver-recall.mjs --error "<original error text>"; if a fix is hit, retry according to it; if still failing → proceed to T4 for deposit.

Complete trigger specifications all in docs/boundary-and-triggers.md — including T2 determination criteria with 3 examples, multi-host concurrency matrix, trigger word ↔ command mapping, three host integration methods, domestic mirrors, and "installed but not working" self-check. This document only retains the core table above; the two locations no longer drift independently. Trigger words are invocation hints, not recall matching mechanisms (matches rely on signals_match × query-token targeting); when a task starts, as long as it's judged as "non-trivial", T1 is executed; no specific word trigger is needed.

Common Misuses (Anti-Pattern Quick Reference)

EN: Anti-pattern quick list - each row explains the MECHANISM, not just the symptom. Full 14-item catalog with [A] evidence: docs/common-mistakes.md. Key ones: success-summary strategies are noise (+36pp worse than nothing), model-may-fail traps have unreliable hit rates, token deltas need a no-injection control group (~-22% repeat-execution baseline), error counting must use authoritative flags (isError=true), cold start needs flow-B deposits first. Each entry includes "Why it's wrong" — explains mechanism rather than phenomenon. Complete list (with more entries) in docs/common-mistakes.md.

Wrong Practice	Why It's Wrong (Mechanism)	Correct Method
strategy contains only a success summary ("Fixed it by checking encoding")	Success summaries are noise; they are filtered by the fix guard at deposit time but waste a deposit slot; if bypassed, they will be filtered by the narration guard at recall time, adding irrelevant latency; +36pp worse than nothing	Write AVOID (what NOT to do) + FIX (specific parameters/commands/encoding)
Using a "model may fail" trap (auto-refine-model can fail) as T2 query	hit rate depends on the model's exact phrasing — unreliable; low signal-to-noise ratio	T3 (error trigger) is the correct scenario; model-probable-fail traps should use concrete task context as query
Using token cost delta (e.g., -30% tokens) to measure inheritance effect without a no-injection control group (measuring what would have cost)	token delta is noisy; any no-injection baseline is needed; without it, ~-22% is the repeat execution baseline, not the effect	Use the full controlled experiment (Flow C): R1 (no injection) → R2 (with injection), compare over multiple tasks
Using tool return value stderr !== "" to count errors	tools often print warnings to stderr; only isError=true is an authoritative flag	Count errors using [E_*] codes in the actual output or the tool's isError attribute
Cold start: run Flow A recall first, expecting hits	An empty store has no genes to recall (FAQ·Q1) — but the user is led to think recall is useless	Run at least one Flow B deposit first to light up the experience store; then recall
Calling session close without matching session open	Unpaired session records bypass the audit gate binding, generating false reports	Always write session open (T1) and close (T5) in matching pairs; run session audit to verify
Submitting all failure fixes to the shared pool	Deposits without environment signal filter contaminate the shared pool with low-quality genes	Only submit with --shareable for generic fixes that are cross-platform cross-architecture
Using --register-hit for any gene used in the script	Hit registration is only for genes actually responded to during user-visible actions; it measures real value	Only register hits for genes that triggered an actionable response during debugging; write a log for the rest

Navigation Map (All Documents)

Each path points to the logical entry; Click to open. Version-by-version updates: CHANGELOG.md.

Path	Signature	Audience	Reading Priority
examples/quickstart.md	5-minute closed-loop example	Beginners	★★★ (start here)
docs/overview.md	Mind map + field glossary	All users	★★★
docs/one-pager.md	One minute decision guide	Skeptical / managers	★★☆ (optional)
docs/common-mistakes.md	14 fallacies + mechanism explanations	Daily users	★★☆ (browse to avoid pitfalls)
docs/boundary-and-triggers.md	Trigger conditions + boundary tables + integration	Power users	★★☆ (read when needed)
docs/advanced.md	Backfill/Concurrency/Provenance/Operations	Maintainers	★☆☆ (as needed)
docs/security-and-license.md	Gate details + compliance	Security auditors	★☆☆ (recommended)
docs/config-errors.md	Common configuration mistakes	All users	★☆☆ (troubleshoot)
docs/research.md	Theory and experiments	Researchers	★☆☆ (low priority)
docs/faq.md	14 Frequently Asked Questions	All users	★☆☆ (as needed)
CONTRIBUTING.md	Pool contributions	Contributors	When submitting genes

---

All documents above are in this repository; some paths are under development. If a document path lacks content, please raise an Issue. This Skill comes from the pi-evox-lab project, integrating evolver and pi frameworks.