Instead of accumulating facts linearly, knowledge evolves: incidents are captured, promoted to behavioral rules when confirmed, and generalized into principles that fire on novel cases never seen before. Memory shrinks as capability grows.

Quick Start

Just want to use it? One command — any OS (Windows, macOS, Linux), no git clone, no Docker, no bash:

npx @muonroi/experience-engine init

init auto-detects a brain and wires your coding agent's hooks for you:

1. A local brain already running at http://localhost:8082 → uses it (no token).
2. Otherwise, if Docker is available, it offers to start the local stack for you.
3. Otherwise it sets up a thin client against a remote brain — point it at one:

npx @muonroi/experience-engine init --server https://your-brain.example.com --token <TOKEN>

Add --yes for a non-interactive install. Windows is supported natively — no Git Bash required.

Keep the brain fed — sync

init wires your agent so it learns going forward. To backfill the brain from this machine's existing agent history (and re-run it periodically), use sync — also cross-platform, no bash:

npx @muonroi/experience-engine sync

It extracts your Claude/Codex/Gemini sessions and imports curated MEMORY.md files into the configured brain (incremental — only new content each run). Useful flags:

npx @muonroi/experience-engine sync --max 100        # extract more sessions this run
npx @muonroi/experience-engine sync --sessions-only  # skip curated-memory import
npx @muonroi/experience-engine sync --memory-only    # only import MEMORY.md
npx @muonroi/experience-engine sync --dry-run        # show what would be sent
npx @muonroi/experience-engine sync --upgrade        # refresh the runtime first, then sync

This is the cross-platform equivalent of bash upgrade.sh --sync-only and honors your thin-client config.json (it POSTs to the configured remote brain). Run it on a schedule (cron / Task Scheduler) to keep the brain current.

Stay current — check-update / update

Check whether a newer release is on npm, and update in place:

npx @muonroi/experience-engine check-update   # compare installed vs registry latest (no changes)
npx @muonroi/experience-engine update          # update if behind
npx @muonroi/experience-engine update --force  # re-run even when already current

check-update exits 0 (up to date), 10 (update available), or 1 (check failed) — handy in scripts. update auto-detects the install mode: a git checkout runs bash upgrade.sh; a plain npm install runs npm i -g @muonroi/experience-engine@latest and then refreshes ~/.experience (cross-platform, no bash needed for the npm path).

Self-host the brain (advanced)

To run the full stack (Qdrant + Ollama + API) on your own machine:

git clone https://github.com/muonroi/experience-engine.git
cd experience-engine
docker compose up -d

Starts Qdrant (6333), Ollama (11434), and Experience Engine API (8082). Zero API keys. Zero config files.

curl http://localhost:8082/health
# {"status":"ok","qdrant":{"status":"ok"},"fileStore":{"status":"ok"}}

Then run npx @muonroi/experience-engine init (or bash .experience/setup.sh for the full local-install wizard) to wire your agent to it.

Documentation

Full documentation at docs.muonroi.com/docs/experience-engine

| Topic | Link | |---|---| | Overview & architecture | Overview | | Getting started | Getting Started | | How it works | How It Works | | Configuration reference | Configuration | | REST API reference | API Reference | | Observability & stats | Observability | | Python SDK | Python SDK |

Agent instructions (auto-managed)

Install and upgrade write a small managed block (delimited by <!-- experience-engine:start --> / <!-- experience-engine:end -->) into each installed agent's config — ~/.claude/CLAUDE.md, ~/.gemini/GEMINI.md, ~/.codex/AGENTS.md, ~/.config/opencode/AGENTS.md — so agents load the Experience Engine workflow at session start. The block is refreshed idempotently on every upgrade.sh, so guidance never goes stale.

The block stays concise and points to the full reference shipped at ~/.experience/AGENT_GUIDE.md (active recall, the feedback verdict table, and the noise decision tree). The two commands agents use:

node ~/.experience/exp-recall.js "<your question>"          # actively query the brain
node ~/.experience/exp-feedback.js followed|ignored|noise <id> <col>   # report the verdict

Use the helper for feedback — never raw curl …:8082/api/feedback, which silently no-ops on thin-client installs.

To manage your own agent config instead, set EXPERIENCE_SKIP_MD_INJECT=1 before running setup/upgrade and the injection is skipped.

Requirements

• Node.js 20+
• One of: Docker · Qdrant Cloud (free tier) · VPS with Qdrant
• One of: Ollama (free, local) · API key for any supported provider

License

MIT © muonroi