ULTRON Control Center

What is this?

Your AI assistant forgets everything every time you close the window: the decisions you made, the errors you already solved, how your project is set up. The next day you have to explain it all over again.

ULTRON gives it memory. While you work, it saves the important stuff on your own computer; when you open a new conversation, it reminds the AI automatically. You do nothing: you work as always and your assistant gets to know you better each time. You decide what gets saved (everything goes through an approval inbox) and nothing leaves your machine.

Local event-sourced memory (brain.db, SQLite) with semantic index (Qdrant + E5 1024d), re-injected in each session via hooks — sub-second hybrid recall with a resident daemon. Plus: AI Router multi-provider, orchestrator of skills/agents and desktop cockpit (Tauri 2 + React 19). All state is local inspectable files. Spec: docs/memory-spec.md.

Related MCP server: MCP Memory Server

With and without ULTRON

Compared to other memory systems (cloud services like Mem0 and similar), the differences are in design, not marketing: here the memory is 100% local (no account, no subscription, no sending your code to a third party), governed (the AI proposes, you approve; every write leaves an audit event), honest (if it doesn't know, it abstains instead of injecting filler — measured) and open (SQLite + Markdown + a standard MCP server that any assistant can query).

Daily usage tutorial (human + AI): docs/TUTORIAL.md · Full memory system spec: docs/memory-spec.md · Component installation: INSTALL.md · MIT License.

How memory flows

flowchart LR
    A[Prompt en Claude Code] -->|hook UserPromptSubmit| B[daemon ultron-memory<br/>E5 residente]
    B --> C[(brain.db<br/>SQLite + FTS5)]
    B --> D[(Qdrant<br/>E5 1024d)]
    C -->|BM25| E[Fusion RRF + cross-encoder]
    D -->|dense| E
    E -->|pack de memorias| A
    F[Fin de sesion] -->|hook Stop| G[Captura -> inbox de candidatos]
    G -->|aprobacion| C
    H[Cualquier cliente MCP<br/>Codex, Gemini CLI...] -->|MCP server| B

Real numbers (measured, not simulated)

Measured on the maintainer's real corpus (~3,300 active memories) with an oracle of 29 hand-labeled queries — your installation starts empty and the recall figures depend on your corpus. Reproducible with ultron-memory eval --golden and the repo scripts.

When the corpus does not know the answer, the system abstains instead of injecting filler — recall honesty is also measured (abstain category of the custom bench).

Quickstart

Full system (app + skills + hooks + semantic memory) — the recommended path; it is idempotent and asks before touching anything:

git clone https://github.com/SkiTemplar/ultron-control-center.git $env:USERPROFILE\.ultron
cd $env:USERPROFILE\.ultron
powershell -ExecutionPolicy Bypass -File .\install.ps1   # Linux: ./install.sh

Component installation (no wizard, deterministic; -DryRun lists the plan without touching anything):

.\install.ps1 -Core            # app + memoria + hooks (el set por defecto)
.\install.ps1 -All             # core + skills + tones + agents
.\install.ps1 -Skills -Tones   # a la carta
.\install.ps1 -Core -DryRun    # solo listar que haria
# Linux: ./install.sh --core | --all | --skills | --tones | --agents | --dry-run

Desktop app only (no skills/hooks/memory sidecar):

git clone https://github.com/SkiTemplar/ultron-control-center.git ~/.ultron && cd ~/.ultron/control-center
cp ../.env.example ../.env   # opcional: claves de proveedores LLM (todas vacias por defecto)
npm install
npm run build:app            # = kill-app + tauri build -> ejecutable de escritorio

Full guide (bootstrap one-liner from release, flags, troubleshooting): INSTALL.md.

Qdrant is optional (recall degrades to sparse-only without it); see the Qdrant section of docs/INSTALL-ADVANCED.md. Per-machine paths are documented in config/paths.example.toml.

Features

• Governed memory — brain.db (SQLite) as the single source of truth; every change goes through a single service that appends an audit event.

• Hybrid recall — dense (E5 1024d / Qdrant) + sparse (FTS5/BM25) fused with Reciprocal Rank Fusion; degrades to sparse-only without Qdrant.

• Candidate inbox — automatic captures propose, human approves; never auto-writes active memory.

• Redaction + dedupe on the write-path — secrets/PII out, duplicates by content_hash out, before persisting or embedding.

• AI Router — primary chain -> fallbacks by zone, key detection and usage/savings telemetry; direct routing in Rust (no LiteLLM sidecar).

• Rule-based orchestrator — maps prompt -> intent -> workflow -> agents -> memories; reserves the large model only for the ambiguous queue.

• Tones / personalities — deterministic detection of chat tone (lexical signals + explicit request) within orchestrate; tones are edited in Library -> Tones. The actual config (~/.ultron/personality.json) is local and gitignored; the repo publishes only the compiled seeds (orchestrator/personality.rs). Tone only dresses the conversation: never commits, docs, or artifacts.

What it is

ULTRON Control Center does not replace Claude Code: it wraps it. It gives it persistent and governed memory, routes requests to various LLM providers based on cost and availability, and automatically detects which specialist skill/agent is suitable for a prompt. All state lives in local files (SQLite + JSON + markdown) that you can inspect, version, and edit by hand.

Backend architecture (real)

The Rust backend lives in control-center/src-tauri/src/. The central memory module is in control-center/src-tauri/src/memory/.

Memory: SQLite as source of truth

• ~/.ultron/brain.db (SQLite, WAL mode) is the canonical SoT. The canonical schema lives in memory/schema_v3.rs (memory) + memory/schema_v4.rs (historical v4 migration: tables edges / unresolved_refs, now inert — the code graph is provided by the external MCP CodeGraph) / memory/migrations.rs, with models in memory/model.rs (MemoryItem, MemoryCandidate, MemoryEvent, and governance enums Status, Scope, Sensitivity, Source, etc.).

• MemoryService (memory/service.rs) is the single persistent writer. Governance invariant: every mutation goes through here and appends a MemoryEvent audit. Hooks and agents never write memory_items directly; they only propose MemoryCandidates that a human (or an auto-approval policy) promotes.

• On the write path, guards are applied: redaction of secrets/PII (memory/redaction.rs) before persisting or embedding, exact dedupe by content_hash (memory/texthash.rs) and lexical dedupe by FTS.

Qdrant: derived index (not source of truth)

• The ultron_memory collection (Qdrant) indexes ACTIVE items with MultilingualE5Large, 1024 dimensions (memory/qdrant_index.rs). It is a derived index: it can be rebuilt at any time with reindex_all and brain.db remains the truth.

• After each approved/edited/restored write, sync_index keeps Qdrant in step with the SoT (best-effort; any drift is detectable/reparable via reconcile).

• The old ultron_sessions collection (384d BGE) is retired; Qdrant here is always an index, never the truth.

Hybrid dense + sparse recall with RRF

• The single recall command (commands/memory/recall_unified.rs) fuses with Reciprocal Rank Fusion (RRF_K = 60):

  • DENSE: E5 vectors in ultron_memory (Qdrant).

  • SPARSE: FTS5/BM25 over memory_items (only status=active).

• Returns a compact context pack of summaries under a token budget (TOKEN_BUDGET = 1500), with traces of why this memory (ranges by source, scores, discards) for the Retrieval Inspector.

• The only recall path is the unified recall command with RRF; the sources are Qdrant (dense) + SQLite/FTS5 (sparse). It does not use external memory services.

Automatic capture via Stop hook

• In Stop, the hook passes the session transcript to memory/capture.rs::capture_session. It:

  1. asks an LLM (via ai_router::route, zone chat) to extract a few durable facts/decisions;

  2. converts each fact into a MemoryCandidate (going through redaction + dedupe) and leaves it in the governed inbox for human approval — never self-promotes to active.

• Fail-safe: if the router has no usable provider, degrades to a cheap local heuristic so the Stop hook never fails.

• The inbox is managed from commands/memory/inbox.rs (memory_inbox_list, approve_candidate, reject_candidate).

AI Router: zones, providers, fallback and telemetry

• Backend in the ai_router/ module (mod.rs + exec.rs + providers/ + seed.rs + store.rs). State in three JSON files under ~/.ultron/cockpit/ai-router/: providers.json (catalog), zones.json (zones with primary + fallbacks), metrics.json (counters + savings).

• route(zone, prompt) traverses the primary -> fallbacks chain, skips providers without a usable API key, records latency/tokens/savings in telemetry and returns Result<String, String> (errors verbatim, never panic, 10s cap).

• Wrappers per provider: anthropic (claude-haiku), codex (OpenAI-compat), gemini, groq, ollama (local, no key), deepseek. Health checks use cheap probes and don't spend tokens; test invocations do.

• Default zones include chat, code-edit, code-review, research-web, code-fast-local, among others.

Orchestrator: automatic detection of skills/agents

• The orchestrator/ module (rules.rs + ranking.rs + orchestrate.rs) maps prompt -> intent -> workflow -> agents to delegate -> memories -> constraints. Intent classification is rule-based (bilingual es/en); the large model is reserved for the ambiguous queue.

• Reuses (does not duplicate): the agent catalog (memory/catalog.rs), the unified recall and the integrated workflows (agent_orchestration.rs). Never writes persistent memory and delegates to real agents in ~/.claude/agents (non-existent "ghost agents" on disk are sanitized).

Code graph: MCP CodeGraph (external)

• The code graph (which symbols exist, who calls whom, impact analysis) is provided by CodeGraph (@colbymchenry/codegraph, MIT), installed as an MCP server and queried by agents via codegraph_explore / codegraph_callers / codegraph_impact. It indexes the repo with tree-sitter (AST) in .codegraph/ (local SQLite, incremental) — 20+ languages.

Plugin Updates: checking for plugin updates

• Sub-tab Updates inside Library (src/components/library/PluginUpdates.tsx) that consumes the backend commands plugin_check_updates_bulk(force) and plugin_changelog_summary(coordinate, installed_sha?).

• Compares the installed SHA against the latest SHA from the marketplace for each plugin, marks which have updates available and shows the latest commit message / changelog summary.

Stack

Sidecar binaries declared in control-center/src-tauri/Cargo.toml: ultron-memory (requires the qdrant feature).

Build

# desde control-center/
npm install
npm run build:app   # = kill-app + tauri build (genera el ejecutable de escritorio)

Other useful scripts (in control-center/package.json):

npm run dev    # vite dev server (frontend)
npm run tauri  # CLI de Tauri
npm test       # vitest (frontend)

Windows note: build:app first runs kill-app to close any running instance; an outdated binary is the usual cause of "the change has not been applied": close the app and recompile.

Folder structure

~/.ultron/
├── brain.db                  # SQLite — fuente de verdad de la memoria
├── qdrant-native/            # binario nativo de Qdrant (indice denso derivado)
├── qdrant_storage/           # datos persistidos por Qdrant
├── control-center/           # la app Tauri 2 + React 19
│   ├── src/                  # frontend React/TS (componentes, tabs)
│   │   └── components/       # Dashboard, AIRouter, Library, Projects, ...
│   └── src-tauri/
│       └── src/
│           ├── memory/       # kernel de memoria (service, sqlite_store,
│           │                 # qdrant_index, capture, redaction, texthash, ...)
│           ├── commands/     # comandos Tauri por dominio (memory, ai_router,
│           │                 # projects, system_ops, ...)
│           ├── ai_router/    # AI Router (mod/exec/health/providers/seed/store/types)
│           ├── orchestrator/ # mod/orchestrate/ranking/rules/types_model
│           └── bin/          # sidecar ultron-memory
├── cockpit/                  # config + estado en JSON/markdown
│   └── ai-router/            # providers.json, zones.json, metrics.json
├── personality.json          # tonos del usuario (LOCAL, gitignored; se
│                             # auto-siembra desde los seeds compilados)
├── hooks/                    # hooks de ciclo de vida
├── skills/                   # skills core (SKILL.md; catalogo curado no se publica)
├── plans/  projects/         # planes y proyectos
├── sessions/                 # logs de sesion / telemetria de routing
└── docs/                     # documentacion ampliada

Current status

• Memory: canonical kernel active. SoT = brain.db; dense index ultron_memory (E5 1024d) synced on write; unified dense+sparse recall with RRF operational (degrades to sparse-only without Qdrant). Write-path with secret redaction and content_hash dedupe wired and tested.

• Automatic capture: Stop hook -> capture_session -> candidates to governed inbox; human approval/rejection via inbox commands.

• AI Router: real routing with primary/fallback chain, key detection and usage/savings telemetry; no LiteLLM sidecar.

• Tones: deterministic detection in orchestrate (JS/Rust detector parity verified with gate 16/16); visual editor in Library -> Tones and detection playground. Local personality.json (gitignored) with compiled publishable seeds; hard limit: tone only applies to chat, never to artifacts.

• AI text detector: PostToolUse hook that warns when written prose "sounds" like AI + deterministic pattern lab over the research catalog; matcher with CLI and test bank. Points out, does not rewrite.

• UI (Control Center, v2.7.1): sidebar with Dashboard, Usage, AI Router, System (with Hooks/Schedules sub-tabs), MCPs, Library (sub-tabs Skills/Agents/Rules/Updates), Memory, Notes, Learn, Sessions, Projects, Finance (only local build with VITE_FINANCE=1), Settings and Notifications. The Memory tab is alive (re-added 2026-06-04, Sidebar.tsx): exposes the candidate inbox (approve/reject/edit) and the health of brain.db; the memory kernel remains backend-only, but its human-in-the-loop governance is done from this tab (in addition to commands).

License

MIT — see LICENSE. Copyright (c) 2026 Rodrigo Fernandez.