ExperienceEngine

English | 简体中文

A local experience-governance layer for coding agents.

ExperienceEngine helps coding agents avoid repeating the same failed execution paths by turning prior task outcomes into short, governed prompt-boundary hints.

Memory helps agents remember context. ExperienceEngine governs whether prior execution experience should intervene.

Supported hosts today: Codex, Claude Code, OpenClaw, and Google Antigravity through different hook / MCP / plugin paths.

10-Second Example

Without ExperienceEngine:

• A coding agent sees a SQLite startup failure.
• It spends several turns debugging connection pool settings.
• It eventually discovers the real issue: the DB connection was opened before the migration ran.
• Days later, in a similar repo or task, it repeats the same failed path.

With ExperienceEngine:

• The prior failure/fix/success path is distilled into a reusable experience node.
• When a similar task starts, ExperienceEngine may inject one compact hint:

Run the migration before opening the DB connection.

• After the run, ExperienceEngine tracks whether that hint helped, harmed, or remained uncertain.
• If the hint keeps helping, it can become more trusted.
• If it starts harming similar tasks, it can cool down, be quarantined, or retire.

Core loop:

task signals
→ distilled experience
→ hybrid retrieval
→ compact intervention
→ helped/harmed feedback
→ governance

Why It Exists

Coding agents are already strong. They can handle large codebases, call tools, follow multi-step tasks, and often recover from mistakes.

But one failure mode still appears often:

The agent eventually solves a problem, but later repeats the same failed execution path in a similar task.

This is not only a context-memory problem. It is an execution-governance problem.

ExperienceEngine is designed to answer:

When should prior execution experience actively guide or constrain a future coding task?

Memory vs ExperienceEngine

ExperienceEngine is not meant to replace memory or RAG.

It is a separate layer focused on:

• repeated failure paths
• task outcomes
• prompt-boundary interventions
• helped/harmed feedback
• lifecycle governance for guidance

What ExperienceEngine Does

ExperienceEngine can:

• capture real task signals from coding-agent runs
• distill repeated failure/fix/success paths into structured experience nodes
• retrieve matching experience before a task begins
• inject compact task-specific guidance instead of dumping long memory into the prompt
• track whether the agent appeared to follow or violate the injected guidance
• record helped/harmed/uncertain outcomes
• reinforce, cool, quarantine, or retire guidance over time
• keep repo/workspace experience scoped by default
• support cautious cross-scope reuse instead of blindly applying one repo’s lesson to another

Architecture

ExperienceEngine works at the context and host-integration layer. It does not modify the host model’s weights.

Experience Node Model

ExperienceEngine does not store generic memories such as:

The SQLite issue was related to migrations.

It tries to distill execution experience into structured nodes:

Trigger pattern:
SQLite startup crash in this repo.

Compact hint:
Run the migration before opening the DB connection.

Recommended steps:
1. Run the migration.
2. Start the app again.
3. Only investigate the connection pool if startup still fails.

Avoid steps:
Do not start by tuning the connection pool.

Success signal:
Startup passes after the migration runs.

Evidence summary:
A previous task failed after connection-pool debugging, then succeeded after migration-first startup.

A node can include:

• trigger pattern
• compact hint
• goal
• recommended steps
• avoid steps
• fallback steps
• success signal
• stop / escalation conditions
• evidence summary
• origin records
• helped / harmed records
• lifecycle state
• delivery state
• portability evidence

Lifecycle vs Delivery

ExperienceEngine separates storage state from delivery behavior.

Lifecycle state:

candidate
→ priority_candidate
→ active
→ cooling
→ retired

Delivery state:

shadow_only
conservative_only
eligible
quarantined
shadow_probe
retired

This separation matters because a node can exist in the store without being allowed to directly affect the agent.

Examples:

• A new candidate can stay shadow_only.
• A promising but unproven node can be conservative_only.
• A validated same-scope node can become eligible.
• Harmful guidance can become quarantined.
• Quarantined guidance can be cautiously tested through shadow_probe.
• Repeatedly harmful guidance can be retired.

Helped / Harmed Feedback

ExperienceEngine does not assume a hint is good just because it was retrieved.

After a task, it can record whether an intervention:

• helped
• weakly helped
• was neutral
• stayed unknown
• weakly harmed
• strongly harmed

Trajectory-aware attribution compares injected expectations against observed tool events when available.

Examples of trajectory verdicts include:

adoption_detected
non_adoption_detected
contra_adoption_detected
guidance_prevented_failure
guidance_caused_failure
trajectory_unknown

When trace evidence is incomplete, ExperienceEngine uses conservative fallback attribution from outcome signals, failure signatures, and harm detection.

Manual feedback is also available:

ee helped
ee harmed

Manual feedback is mainly for correcting the automatic judgment, not for grading every run.

Host Support Matrix

Different hosts expose different hook surfaces, so the integration path and maturity are not identical.

Quick Start

1. Install the CLI

npm install -g @alan512/experienceengine

Node.js >=20 is required.

Trust boundary: ExperienceEngine host integrations install lifecycle hooks that can observe prompt, tool, and session events. Managed installs may modify persistent user-level agent configuration and store local state under ~/.experienceengine. Normal trace persistence is metadata-only, but raw OpenClaw payload capture is an explicit sensitive-data opt-in. When remote embedding, distillation, explanation, or posttask-review providers are configured, selected task content is sent to those providers. Review the host-specific file changes below and back up relevant agent configuration before installation.

2. Choose your host

Codex

ee install codex
ee init

Then open a fresh Codex session in your repo.

If Codex asks you to review hooks, open:

/hooks

Approve the ExperienceEngine hooks:

UserPromptSubmit
PostToolUse
Stop

PreToolUse is not registered by default. It is only for synchronous gating experiments.

Claude Code

Preferred marketplace path:

/plugin marketplace add https://github.com/Alan-512/ExperienceEngine.git
/plugin install experienceengine@experienceengine

Then run:

ee init

Fallback path:

ee install claude-code
ee init

Start a fresh Claude Code session so plugin hooks and MCP config are loaded.

OpenClaw

openclaw plugins install @alan512/experienceengine
openclaw gateway restart
ee init

The v0.5.x package line contains a package-local supervisor/worker runtime. Plugin load alone still proves only routine interaction: a loaded plugin can have interaction_active = true while learning_runtime_active or production_learning_ready remains false.

Use the authenticated OpenClaw commands to inspect and, when required, initialize the exact installed package generation:

/experienceengine_status
/experienceengine_prepare_package_activation

The preparation command is read-only. Copy the exact JSON object returned in its result field into:

/experienceengine_initialize_package_activation <exact-result-json>

Then verify current authority from the operator CLI:

ee verify openclaw-production

The implementation has passed local-pack real-host preflight on WSL/Linux and native Windows. Exact published npm v0.5.2 independently passed the full OpenClaw 2026.7.1 WSL live-host sequence. A later public ClawHub v0.5.2 entry exists, but its uploaded archive is incomplete, omits the built runtime, and fails exact closure validation; do not install that channel version. v0.5.3 is the immutable repair release. The earlier repeated single-scenario campaign passed its sealed thresholds, and the fresh published-npm v5 campaign completed all nine treatment/forced-holdout/no-EE arms across inject, correct-skip, and harm-recovery scenarios. Independent validation proved correct skip with zero false-positive delivery plus deterministic harmful exposure, production feedback/quarantine, and fresh-session recovery. V5 remains directional and not_publishable because it has one repetition per scenario and intentionally includes harmful exposure; it is not a general efficacy or full-support claim. support_claim_allowed and production_learning_ready remain false.

The operator fallback is:

ee install openclaw
openclaw gateway restart
ee verify openclaw-production

If OpenClaw requests security approval, review its findings and explicitly rerun with --approve-host-security-scan. ExperienceEngine does not add the unsafe-install flag by default.

Google Antigravity

ee install antigravity
ee init

For CLI runs:

ee agy exec -C <project-path> "<prompt>"

Antigravity support covers Agent Desktop, the standalone agy CLI, and observed IDE hook/MCP surfaces where available.

Shared Initialization

ee init configures shared ExperienceEngine state.

It can configure:

• distillation provider
• distillation model
• provider authentication
• optional LLM fallback chain
• embedding mode
• embedding provider
• shared secrets

Example:

ee init distillation --provider openai --model gpt-4.1-mini --auth-mode api_key
ee init secret OPENAI_API_KEY <your-api-key>
ee init embedding --mode api --api-provider openai --model text-embedding-3-small
ee init show

For provider-level fallback, set an EE fallback chain:

ee init distillation --provider openrouter --model google/gemma-4-31b-it:free --fallback-chain "gemini:gemini-2.5-flash,openai:gpt-4o-mini"
ee init secret OPENROUTER_API_KEY <your-openrouter-key>
ee init secret GEMINI_API_KEY <your-gemini-key>
ee init secret OPENAI_API_KEY <your-openai-key>

You can also manage fallback after initialization:

ee config set distillation.fallback_chain "gemini:gemini-2.5-flash,openai:gpt-4o-mini"
ee config set distillation.fallback_codes "429,500,502,503,504"
ee config unset distillation.fallback_chain

distillation.fallback_chain is an ExperienceEngine-level chain across providers. OpenRouter's EXPERIENCE_ENGINE_FALLBACK_MODELS secret is different: it sends a models list inside one OpenRouter request. Use the OpenRouter secret for same-provider model fallback, and use distillation.fallback_chain when you want ExperienceEngine to move to another configured provider after fallbackable HTTP statuses.

You can also configure Gemini or Jina for embeddings through the same ee init embedding flow.

Data Location

By default, ExperienceEngine stores product state under:

~/.experienceengine

That managed state can include:

• SQLite database
• product settings
• per-adapter install state
• optional local embedding model cache
• managed backups
• exports
• rollback snapshots

Model and embedding providers depend on configuration. ExperienceEngine is local-first for product state, but not necessarily fully offline unless configured that way.

Embedding Defaults

Current default behavior:

• embeddingProvider = "api"
• provider priority: OpenAI → Gemini → Jina
• if no API provider is available, ExperienceEngine falls back to legacy hash-based retrieval
• local semantic embeddings are optional and not installed by default

Useful environment variables:

EXPERIENCE_ENGINE_EMBEDDING_PROVIDER=local
EXPERIENCE_ENGINE_EMBEDDING_API_PROVIDER=openai|gemini|jina

To force local embeddings after installing the optional local runtime:

npm install -g @huggingface/transformers

Routine Use

In normal use, stay inside your host agent first.

Ask questions like:

What did ExperienceEngine just inject?
Why did that ExperienceEngine hint match?
Why didn't ExperienceEngine inject anything just now?
Mark the last ExperienceEngine intervention as helpful.
Mark the last ExperienceEngine intervention as harmful.

Use CLI fallback when you need explicit operator control:

ee status
ee status --verbose
ee doctor codex
ee doctor claude-code
ee doctor openclaw
ee doctor antigravity
ee inspect --last
ee helped
ee harmed

ee status is the concise daily progress view. Use ee status --verbose for host wiring details, model configuration, raw retrieval counters, second-opinion counters, and learning-quality diagnostics.

Privacy-safe diagnostic reports

Use diagnostics only when you need to prepare a report for review or an issue:

ee diagnose
ee diagnose --prepare-bundle
# inspect the generated manifest.json locally
ee diagnose --archive <review-directory>

ee diagnose is read-only and does not initialize a missing ExperienceEngine home, key, or database. Bundle preparation creates a new review directory containing only manifest.json. Archive creation revalidates that exact manifest and creates a local deterministic .tar.gz containing only that file.

No upload or issue submission occurs automatically. Review the manifest before sharing. Do not attach raw SQLite files, settings, prompts, source code, paths, credentials, tool output, provider requests/responses, or unreviewed logs. Exact model identity is excluded unless you explicitly add --include-model-id during diagnosis or bundle preparation.

The exact published npm v0.5.2 CLI independently passed this clean-home diagnose/prepare/archive flow, including deterministic archive bytes, exact one-file content, privacy scans, overwrite refusal, and extra-file rejection. This is npm-channel diagnostics evidence, not a ClawHub v0.5.2 or general support claim.

Use the repository issue templates for installation problems, runtime bugs, harmful interventions, and feature requests. Use the private security-reporting guidance in SECURITY.md for vulnerabilities or privacy leaks.

Readiness and Value States

ExperienceEngine separates setup readiness from actual value.

Setup state:

Installed
Initialized
Ready

Value state:

Warming up
First value reached

A repo can be fully Ready while still Warming up.

First value reached should only be claimed after a real task shows visible value, such as:

• a repeated task avoids a previously known bad path
• a compact repo-relevant hint is injected
• the host can explain why the hint matched
• the task outcome updates future delivery
• ee inspect --last shows the recent intervention and node state

A generic warm-up message does not count as first value.

What First Success Looks Like

After installation and initialization, a good first success looks like this:

1. You run a task similar to a previous failure/fix path.
2. ExperienceEngine injects a short relevant hint.
3. The host agent avoids the old failed path.
4. The task succeeds or produces useful evidence.
5. ExperienceEngine updates the node’s helped/harmed/uncertain state.
6. ee inspect --last explains what happened.

Example:

ee inspect --last --verbose

Why Not Just Put This In AGENTS.md?

AGENTS.md is useful for stable, global project instructions.

ExperienceEngine is for guidance that may be:

• repo-local
• workflow-local
• task-family-specific
• still unproven
• possibly harmful outside its original context
• not ready to become a permanent rule

A good rule can eventually become documentation or a project convention. ExperienceEngine is the governed proving ground before that.

Safety Model

ExperienceEngine tries to avoid turning old experience into new prompt noise.

Key safeguards:

• compact interventions instead of long memory dumps
• same-scope experience is preferred
• cross-scope reuse is cautious
• destructive cross-repo guidance can be blocked
• dependency and major-version compatibility checks inform portability scoring
• harmful guidance can cool down, be quarantined, or retire
• uncertain nodes can stay shadow-only or conservative-only
• shadow-probe recovery allows quarantined guidance to be tested cautiously
• decisions are persisted so skipped turns can be inspected later

The product goal is production-safe reuse, not maximum recall.

Retrieval

ExperienceEngine uses hybrid retrieval rather than semantic similarity alone.

The retrieval path can include:

• query rewriting
• lexical retrieval
• semantic retrieval
• rank fusion
• policy enrichment
• task-family matching
• scope matching
• failure-signature matching
• artifact / tech-stack matching
• reranking
• delivery-state gating

Semantic similarity is useful, but it is not treated as the only authority.

Cross-Scope Portability

ExperienceEngine is workspace/repo-scoped by default.

Cross-scope reuse is intentionally cautious.

Portability checks can consider:

• same-scope vs cross-scope match
• primary language compatibility
• shared dependencies
• framework / ORM / runtime differences
• major-version mismatch penalties
• destructive guidance patterns
• historical harm
• successful reuse evidence under compatible fingerprints

Portability bands include:

validated_portable
same_family
weakly_related
incompatible

Cross-scope guidance should earn trust through reuse evidence, not be blindly applied.

Background Hygiene

ExperienceEngine includes background hygiene for experience quality.

It can help with:

• duplicate nodes
• conflicting guidance
• stale shadow-only nodes
• harmful live guidance
• risky delivery states
• conservative restoration after quarantine

High-impact actions are guarded. Broad rewrites, unsafe deletes, and risky automatic changes are rejected or converted into safer operations.

For normal users, this should mostly stay in the background.

Inspection surfaces:

ee inspect review
ee inspect hygiene
ee inspect repo

Operator fallback:

ee maintenance governance drain

CLI Reference

Common commands:

ee init
ee status
ee doctor <openclaw|claude-code|codex|antigravity>
ee inspect --last
ee inspect --trace <capsule-id>
ee helped
ee harmed

Host setup and repair:

ee install codex
ee install claude-code
ee install antigravity
ee repair codex
ee repair antigravity

OpenClaw host-native routine interaction uses:

openclaw plugins install @alan512/experienceengine
openclaw gateway restart

For the operator-managed fallback and strict runtime verification:

ee install openclaw
ee verify openclaw-production

Backup and recovery:

ee backup
ee export
ee import <snapshot-path>
ee rollback <backup-id>

Advanced / operator commands:

ee maintenance embedding-smoke
ee maintenance governance drain
ee maintenance redistill-rule-nodes
ee maintenance merge-scope <sourceScopeId> <targetScopeId>

Most users should not need advanced maintenance commands during normal use.

Advanced Host Notes

Codex

Codex integration uses Codex-native hooks plus the shared ExperienceEngine MCP server.

Default hooks:

UserPromptSubmit
PostToolUse
Stop

Notes:

• UserPromptSubmit owns prompt-time experience injection.
• PostToolUse and Stop are queued for background processing by default.
• PreToolUse is not registered by default.
• In mixed Windows Codex App + WSL Codex CLI setups, global hooks may be shared while MCP config is runtime-specific.
• ee repair codex can refresh global hooks and remove stale project-scoped MCP config.

Manual MCP fallback:

codex mcp add experienceengine --env EXPERIENCE_ENGINE_HOME=$HOME/.experienceengine -- npx -y @alan512/experienceengine codex-mcp-server

Claude Code

Claude Code supports the bundled marketplace/plugin path:

/plugin marketplace add https://github.com/Alan-512/ExperienceEngine.git
/plugin install experienceengine@experienceengine

Fallback:

ee install claude-code

Start a fresh Claude Code session after installation.

OpenClaw

OpenClaw exposes host-native plugin interaction and a package-local supervisor/worker runtime. The runtime has passed local-pack real-host preflight and exact published npm and ClawHub 0.5.1 validation, including Gateway restart, fenced queue completion, stale-output rejection, and graceful shutdown. The disclosed repeated matched-block campaign passed its sealed single-scenario thresholds, but the general full-support claim remains disabled because the evidence contains one scenario cluster and production_learning_ready=false remains authoritative.

openclaw plugins install @alan512/experienceengine
openclaw gateway restart

These three states are intentionally separate:

interaction_active
learning_runtime_active
production_learning_ready

Plugin load or successful routine interaction satisfies only the first state. Use ee verify openclaw-production for a strict non-zero automation gate; ee status remains informational.

For a cold package generation, use the authenticated host-native control sequence:

/experienceengine_status
/experienceengine_prepare_package_activation
/experienceengine_initialize_package_activation <exact-result-json>

prepare_package_activation is read-only and returns the exact current package generation, projection revision, launch revision, control request id, and authorization id required by the initialization command. Missing or changed required identity, revision, or idempotency fields are rejected; do not reuse a stale payload.

artifact_runtime_validated is also separate from support_claim_allowed: an exact artifact can pass runtime execution while the channel/platform/quality publication gates remain pending.

If OpenClaw reports only a global workspace, ExperienceEngine isolates that session rather than reusing unrelated global-workspace experience.

Google Antigravity

Antigravity support includes:

• Agent Desktop user-level plugin/MCP wiring
• agy CLI integration
• observed IDE global hook/MCP surfaces where available

Install:

ee install antigravity

CLI run:

ee agy exec -C <project-path> "<prompt>"

Project-local fallback:

ee antigravity activate-project -C <project-path>

Antigravity behavior can vary by environment, so use:

ee doctor antigravity

to inspect the current installation and observed surfaces.

Who It Is For

Use ExperienceEngine if:

• you use coding agents repeatedly in similar repos or workflows
• you see agents rediscovering the same fixes
• you want compact guidance instead of broad memory recall
• you care whether a reused hint actually helped or harmed
• you want stale or harmful guidance to cool down instead of accumulating forever

Do not use ExperienceEngine if:

• you only want personal note-taking memory
• you want generic document RAG
• you rarely repeat workflows
• you want everything remembered by default
• you expect model-weight training or permanent fine-tuning

Project Status

Stable:

• core experience lifecycle
• prompt-boundary intervention flow
• inspect / helped / harmed loop
• local SQLite-backed product state
• host integrations
• CLI/operator fallback

Supported hosts:

• Codex
• Claude Code
• OpenClaw
• Google Antigravity

Evolving:

• retrieval tuning
• provider strategy
• advanced host UX
• cross-scope portability tuning
• richer trajectory attribution
• background hygiene behavior

The project is early. Feedback from heavy coding-agent users is especially useful.

Documentation

Additional documentation:

• Experience Model Overview
• ExperienceEngine User Guide
• Contributing
• Security Policy

Suggested future docs:

• docs/hosts/codex.md
• docs/hosts/claude-code.md
• docs/hosts/openclaw.md
• docs/hosts/antigravity.md
• docs/governance.md
• docs/troubleshooting.md

License

MIT License.

See LICENSE.