Skip to main content

Getting Started with Experience Engine

Experience Engine is a local-first AI memory system that learns from your development patterns. If you only want to use it, one command installs and wires everything — no clone, no Docker, no bash.

Works on any OS (Windows, macOS, Linux). No git clone, no Docker, no Git Bash:

npx @muonroi/experience-engine init

init auto-detects a brain and wires your coding agent's hooks for you, resolving the mode in this order:

  1. A local brain already running at http://localhost:8082 → uses it (no token needed).
  2. Otherwise, if Docker is available, it offers to start the local stack for you.
  3. Otherwise it configures a thin client against a remote brain — point it at yours:
npx @muonroi/experience-engine init \
--server https://your-vps:8082 \
--token YOUR_TOKEN

Add --yes for a fully non-interactive install. Useful flags:

FlagPurpose
--server URLRemote brain base URL (thin-client mode)
--token TOKENBearer token for write/feedback endpoints
--read-token TOKENRead-only token for /api/stats, /api/gates
--local / --remoteForce a mode instead of auto-detecting
--agents claude,codexWire only specific agents
--yes, -yNon-interactive (never prompts, never runs Docker)

Config is saved to ~/.experience/config.json. Re-running init is idempotent (preserves org settings, dedups hooks). Restart your agent session afterward so it picks up the new hooks.

Already have a brain on a VPS?

On a clean machine, skip all prompts: npx @muonroi/experience-engine init --server https://your-vps:8082 --token YOUR_TOKEN --yes

Feed the brain — sync​

init makes your agent learn going forward. To backfill the brain from this machine's existing agent history — and to top it up periodically — run sync (also cross-platform, no bash, no repo checkout):

npx @muonroi/experience-engine sync

It scans your Claude/Codex/Gemini sessions and curated MEMORY.md files and pushes new experiences to the configured brain. Incremental and idempotent — each run only sends what changed since the last.

FlagEffect
--max NMax sessions to extract this run (default 30)
--max-age DUROnly sessions newer than DUR, e.g. 90d (default 365d)
--runtime CSVLimit to claude,codex,gemini,muonroi-cli,antigravity
--project SLUGLimit to one project slug
--sessions-onlySkip curated-memory import
--memory-onlyOnly import MEMORY.md
--include-referenceAlso import reference-type memory
--reset-markerReprocess everything (ignore incremental markers)
--upgradeRefresh the thin-client runtime (init --yes) first, then sync
--dry-runDetect only; write nothing
-vVerbose per-item output

It honors ~/.experience/config.json, so a thin client POSTs to your remote brain. This is the cross-platform equivalent of bash upgrade.sh --sync-only. Schedule it (cron on Linux/macOS, Task Scheduler on Windows) to keep the brain current.

Recommended cadence

After the first init, run npx @muonroi/experience-engine sync once to backfill, then on a daily schedule. Use --upgrade occasionally to also refresh the runtime in the same pass.

Self-host the brain (Docker)​

To run the full stack (Qdrant + Ollama + API) on your own machine, then point init at it. Starts Qdrant (vector store), Ollama (embeddings), and Experience Engine API in one command.

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

This starts three services:

  • Qdrant (port 6333) — vector storage for memories
  • Ollama (port 11434) — embedding models, auto-pulled on first run
  • Experience Engine API (port 8082) — main service

Verify the setup:

curl http://localhost:8082/health

Response:

{
"status": "ok",
"qdrant": {
"status": "ok"
},
"fileStore": {
"status": "ok"
}
}

Everything runs locally. Zero API keys. Zero config files.

Full local-install wizard (setup.sh)​

For advanced configuration (choosing vector store, embedding/brain providers, and which agents to wire), use the interactive bash wizard. This is the heavier path — prefer npx … init unless you need to pick providers:

bash .experience/setup.sh

The script walks you through four steps:

Step A — Vector Store

  • Qdrant Cloud (managed, account required)
  • Local Docker (recommended for development)
  • VPS SSH Tunnel (for thin client architectures)

Step B — Embedding Provider

  • OpenAI (requires API key)
  • Gemini (requires API key)
  • SiliconFlow
  • VoyageAI
  • Ollama (local, no keys)
  • Custom

Step C — Brain Provider (LLM for knowledge extraction)

  • OpenAI
  • Gemini
  • Claude
  • DeepSeek
  • SiliconFlow
  • Ollama (local, no keys)
  • Custom

Step D — Agent Wiring

  • Claude Code (recommended)
  • Gemini CLI
  • Codex CLI
  • OpenCode

Configuration is saved to ~/.experience/config.json.

Thin Client Setup (Team/VPS)​

If your team runs a shared Experience Engine on a VPS, connect your workstation as a thin client. The cross-platform init command is the simplest path:

npx @muonroi/experience-engine init \
--server http://your-vps:8082 \
--token YOUR_TOKEN --yes

The legacy bash installer is still available (npx @muonroi/experience-engine setup-thin-client --server … --token …), but requires bash/Git Bash on Windows.

Config saved to ~/.experience/config.json:

{
"serverBaseUrl": "http://your-vps:8082",
"serverAuthToken": "your-token"
}

Thin Client Architecture:

  • VPS holds: Qdrant, embed/brain API keys, all extracted knowledge, evolution jobs
  • Your machine holds: hooks, local event queue, configuration
  • Offline support: Events queue locally and drain automatically when VPS comes online
  • Instant onboarding: New developer runs one command and instantly accesses team's accumulated knowledge

Bootstrap from Existing Memory​

The recommended import path uses the adapter-based import-memory.js tool, which supports all four runtimes (Claude, Gemini, Antigravity, Codex) and is mtime-gated so only changed files re-import:

node .experience/tools/import-memory.js

This scans ~/.claude/projects/*/memory/, ~/.gemini/projects/*/memory/MEMORY.md, ~/.gemini/antigravity/projects/*/memory/MEMORY.md, and ~/.codex/projects/*/memory/MEMORY.md, then upserts entries into the brain.

Legacy path (Claude-only): node tools/experience-bulk-seed.js --memory-dir ~/.claude/projects/*/memory still works for Claude projects but is not adapter-aware and does not cover Gemini, Antigravity, or Codex memory. Prefer import-memory.js for new setups.

See Memory Adapters for full CLI flags, type routing, and the MEMORY.md bullet format.

Upgrade (existing installs)​

To refresh an existing install with the latest code and sync all agent sessions into the brain:

bash upgrade.sh

What this does:

  1. git pull --ff-only to fetch the latest code
  2. Detects your install mode from ~/.experience/config.json (thin-client or full)
  3. Delegates to the appropriate setup script to refresh the runtime
  4. Step 4 — Session sync: runs bulk-extract.js to extract new experiences from local agent sessions, then runs import-memory.js to sync curated agent memory from all four runtime adapters

Options:

FlagDescription
--sync-onlySkip pull and runtime refresh; only run Step 4 (bulk-extract + import-memory)
--no-syncSkip Step 4 entirely (pull + runtime refresh only)
--no-pullSkip git pull, run everything else
--dry-runPrint what would happen; change nothing
--sync-max NLimit session extraction batch size (default 30)

Wiring to Claude Code​

Once Experience Engine is running, integrate it with Claude Code for automatic PreToolUse warnings:

Config file: ~/.experience/config.json

{
"serverBaseUrl": "http://your-vps:8082",
"serverAuthToken": "your-token"
}

No additional wiring is needed. The hooks inject experience-based warnings automatically before Edit/Write/Bash calls. See your project's CLAUDE.md for integration details.


Agent Hook Compatibility​

AgentWindowsmacOS / LinuxWSL
Claude CodeWorksWorks—
Gemini CLIWorksWorks—
Codex CLIHooks disabledWorksWorks
OpenCodeWorksWorks—

Windows installs: npx @muonroi/experience-engine init runs natively — no Git Bash required (hook commands invoke node with absolute paths). The bash setup.sh / setup-thin-client.sh paths still need Git Bash or WSL.

Codex on Windows: Run Codex from WSL. The setup.sh script handles all WSL-specific hook wiring automatically.


Next Steps​

  • Overview — Understand how Experience Engine works
  • Configuration — Configure providers, storage, and wiring
  • How It Works — Learn about memories, hooks, and the feedback loop