Skip to main content

Experience Engine Observability & Admin Tools

The Experience Engine provides a comprehensive suite of observability tools and admin commands to monitor health, track learning velocity, inspect knowledge graphs, and manage the knowledge base.

Stats & Metrics​

Monitor learning velocity and usage patterns with the stats command:

node tools/exp-stats.js              # last 7 days
node tools/exp-stats.js --since 30d  # custom window
node tools/exp-stats.js --all        # all time

Output includes:

  • Hit rate: percentage of suggestions successfully applied
  • Mistakes avoided: count of errors prevented by hints
  • Velocity: lessons learned per week
  • Tier distribution: confidence level breakdown of entries

The same metrics are available via REST:

curl http://localhost:8082/api/stats

Health Check​

Run a 14-point diagnostic dashboard to verify all Experience Engine systems:

bash ~/.experience/health-check.sh        # interactive dashboard
bash ~/.experience/health-check.sh --json # machine-readable output
bash ~/.experience/health-check.sh --watch # auto-refresh every 30s

View the last persisted health snapshot:

exp-health-last

The health check validates:

  • Configuration files and paths
  • SSH tunnel connectivity (for VPS deployments)
  • Qdrant vector database availability
  • Embedding API responsiveness
  • Brain API connectivity
  • Core system files
  • Agent hook wiring
  • Activity log integrity
  • Model routing configuration

Gates Inspection​

Check server-side readiness for each operational gate:

node tools/exp-gates.js

Or via REST:

curl http://localhost:8082/api/gates

Each gate reports status as PASS, WARN, or FAIL:

  • Qdrant: Vector database availability
  • Embed: Embedding service health
  • Brain: Brain API connectivity
  • Hooks: Agent hook wiring status

Knowledge Graph​

Inspect relationships between experience entries using the knowledge graph API:

curl "http://localhost:8082/api/graph?id=<experience-id>"

Response includes graph edges such as:

  • generalizes: broader principle this entry generalizes from
  • relates-to: related entries and lessons
  • supersedes: entries this one has replaced or improved upon

Example:

curl "http://localhost:8082/api/graph?id=a1b2c3d4"

Timeline (Knowledge Evolution)​

View the complete evolution of a topic across all related entries:

curl "http://localhost:8082/api/timeline?topic=dependency+injection"

The timeline shows:

  • Which entries superseded which over time
  • Timestamps of revisions and refinements
  • The current consensus principle or best practice
  • Historical context for decision reversals

Admin Tools​

ToolCommandPurpose
Statsnode tools/exp-stats.jsUsage and velocity metrics across time windows
Gatesnode tools/exp-gates.jsServer readiness check for all operational gates
Dogfood Loopnode tools/exp-dogfood-loop.jsControlled live confirmation loop for organic lessons
Holdout Harnessnode tools/exp-holdout-harness.jsSeed-vs-holdout replay to prove novel-case coverage
Demotenode tools/exp-demote.jsDemotion or reclassification of entries
Backupnode tools/exp-portable-backup.jsPortable export of knowledge base
Restorenode tools/exp-portable-restore.jsPortable restore to new machine or VPS
Replay Sessionsnode tools/exp-replay-sessions.jsReplay recorded session events for analysis
Server Maintainnode tools/exp-server-maintain.jsServer maintenance and cleanup flow
Bulk Seednode tools/experience-bulk-seed.jsBulk seeding from existing memory directories

Portable Backup & Restore​

Export the entire knowledge base for transfer to new machines or VPS deployments:

# Export to JSON
node tools/exp-portable-backup.js --output backup-2025-05.json

# Restore on new machine or VPS
node tools/exp-portable-restore.js --input backup-2025-05.json

Backup files are self-contained JSON exports that include all entries, confidence scores, relationships, and metadata.

Seeding from Existing Memory​

Bootstrap the Experience Engine from existing Claude project memories:

node tools/experience-bulk-seed.js --memory-dir ~/.claude/projects/*/memory

This allows you to:

  • Migrate experience entries between machines
  • Seed new installations with lessons from established projects
  • Accelerate learning rather than waiting for organic feedback

Specify memory directories from Claude project folders, workspace memories, or other structured knowledge bases.