Free Store
Get started

Development Guide

Development commands, setup instructions, testing, and project status for Quox contributors.

This document covers development commands, setup, testing, and current project status.

Development Commands

Start Services

bash
cd /opt/n8n && docker compose up -d

Build Dashboard

bash
cd /home/control/quox-dashboard && npm run build

Development Mode

bash
npm run dev

View Logs

bash
docker logs n8n -f
docker logs quox-dashboard -f

API Key Configuration

Edit /opt/n8n/.env:

env
OPENAI_API_KEY=sk-...      # For Whisper STT
ELEVENLABS_API_KEY=...     # For TTS

Then restart:

bash
docker compose restart n8n

Testing

Memory System Tests

bash
# Located at src/test/memoryManager.test.js
# 103 tests covering memory operations
npm test

Workflow Library Management

bash
# Re-index workflow library (after adding new templates)
node scripts/index-workflows.cjs [source-dir] [output-file]

# Default source: /home/control/uploads/AI_Agent_Vault_extracted/AI_Agent_Vault-main
# Default output: src/config/workflow-library-index.json

# Setup public symlink for on-demand JSON loading
ln -s /home/control/uploads/AI_Agent_Vault_extracted \
      /home/control/quox-dashboard/public/workflows

Current State

Working Features

  • Command Center with multi-view interface (Chat, Infra, Activity, Settings)
  • Voice interface with audio-reactive visualizer
  • Memory system with episodic, semantic, and entity memory
  • Hybrid retrieval (vector + keyword with RRF fusion)
  • User preference categories (communication, technical, workflow, time)
  • Memory consolidation and contradiction detection
  • Profile editing with memory stats display
  • Proxmox panel with cluster/VM/container views
  • Voice mode switching (Assistant/Cyberpunk/Precise)
  • Claude chat via webhooks with memory context injection
  • Safety system with DEFCON levels and operation guards
  • MHA Fleet Panel - Real-time fleet status in Infra view
  • MHA Auto-Detection - Prompts to install MHA on hosts without it
  • MHA Deployment Tools - Scripts for easy fleet-wide installation
  • Universal Agent Monitor (UAM) - Real-time AI agent session tracking across fleet
  • QUOX Self-Awareness - Hardwired knowledge injection for all LLM calls
  • Centralized Host Registry - All hosts with aliases in one config
  • AEE Protocol - Full audit trail with conversation threading (IndexedDB + SQLite)
  • Activity View - Browse/filter conversations, click to continue
  • AEE Memory Bridge - Auto-extract memories from completed conversations
  • AEE Analytics - Pattern detection, anomaly detection, dashboard stats
  • Reflection Loop - Self-improvement daemon (OBSERVE -> ANALYZE -> LEARN -> ACT)
  • Proactive Context - Recent activity & incomplete tasks injected into chat
  • New Agents - ORACLE (analytics) and ARCHIVIST (memory) capabilities
  • Memory Overhaul Wave 1+2 - Provenance, confidence, truth strategy, semantic embeddings
  • Memory Overhaul Wave 3 - Runbook compiler, agent permissions, intent tracking
  • Memory Overhaul Wave 4 - Metrics dashboard, memory management UI, visualizations
  • Plugin Management - Settings UI for license activation and plugin enable/disable with tab gating
  • Smart Router - Pattern matching to bypass LLM for common operations (mha install, fleet status, etc.)
  • Style Engine - User communication style learning and response adaptation (Phase 8)
  • ChatGPT Importer - Import conversations from ChatGPT exports with memory extraction (Phase 10)
  • Working Set Memory - The "RAM" of user relationship - active context, open loops, recent entities
  • Workflow Library - 1,340 indexed workflow templates with category/integration filtering
  • WireMap Visual Viewer - React Flow-based n8n workflow diagrams with hover/click interaction

Needs Testing

  • Voice input (needs OpenAI API key)
  • Voice output (needs ElevenLabs API key)
  • Direct Proxmox API (CORS blocked, use n8n proxy)

In Development

Smart Router (Layer 1 Pattern Matching)

The Smart Router intercepts user queries and handles many operations without invoking the LLM, providing faster responses and reduced costs.

Concept:

  • Pattern matching for common commands and queries
  • Direct action execution for infrastructure operations
  • LLM bypass for deterministic tasks

Files (when implemented):

  • src/services/smartRouter.js - Pattern matcher and router
  • src/config/routerPatterns.js - Pattern definitions

Pattern Categories (planned):

  • Infrastructure commands: "restart nw-worker-01", "check nginx status"
  • Memory commands: "remember this", "what do you know about X"
  • Navigation: "show me hosts", "open settings"
  • Quick actions: "deploy to production", "run tests"

Memory Commands (Phase 9)

Explicit memory management via natural language:

  • "Remember this: ..." - Explicit memory storage
  • "Forget about ..." - Memory deletion
  • "What do you know about ..." - Memory retrieval
  • "Update my preference for ..." - Preference modification

Files (when implemented):

  • src/services/memoryCommands.js - Natural language memory interface

Planned Features

  • Multi-agent development team
  • Per-agent memory specialization
  • Cross-encoder reranking
  • Guardrail audit (reduce over-triggering of safety warnings)

Known Limitations

  1. Voice requires API keys (not pre-configured)
  2. SSH may fail if bastion connection drops
  3. Browser may block autoplay audio
  4. No authentication on dashboard (yet)
  5. Direct Proxmox API calls blocked by CORS (use n8n proxy)

Contact