A local-first personal AI agent that runs on my PC, orchestrates other agents, and never gets unsupervised root.
ORACLE is not "a chatbot with shell access". It is a small orchestrator that understands intent, selects a capability, routes work to the cheapest competent executor, and reports back — while every side effect passes through a policy layer that can refuse.
You ──▶ ORACLE ──▶ intent ──▶ route ──┬─▶ local tool (fast, free, guarded)
▲ ├─▶ project knowledge (hybrid retrieval)
│ ├─▶ Claude Code (deep code reasoning)
│ ├─▶ Antigravity (alternate coding agent)
│ └─▶ pipeline (declarative workflow)
└──────────────── result ◀───────────┘
The local model is deliberately small. It is a router and a narrator, not the thing that writes your code. Heavy reasoning is delegated to agents that are good at it; ORACLE's value is knowing what to delegate, with what context, and what to allow.
★ Phases 0–10 are built. In progress: Phase 11 — Execution visualisation. Next: Phase 12 — Project state & the continue loop, the phase that makes "continue Asterim" answerable. What the product is meant to be is docs/VISION.md.
ORACLE runs, routes, acts, retrieves, delegates, plans and remembers. Ask it to check a repository
and it runs git.status and shows you the card. Ask it to push and it stops and shows you the
commits that would leave the machine. Give it an objective and it produces a plan, turns the plan
into a task graph, and runs the graph across local tools and Claude — asking before every side
effect and before anything leaves the machine. Type in the terminal dock and your keystrokes reach
a real ConPTY inside a Job Object that the HALT key can kill.
| Tools | 33 contracts behind the policy gate |
| Pipelines | declarative YAML workflows that compile to task graphs — one approval up front, no second executor |
| Tests | 1,061 Python + 171 TypeScript; the security suite is a merge gate |
| Router | qwen3.5:0.8b, 93.3% intent accuracy, 100% tool selection on the eval set |
| Knowledge | hybrid retrieval over the real corpus, bge-m3; the recall gate is unmet and stated (OQ-18) |
| Supervision | task graphs, a planner tier with a fallback ladder, bounded replanning, crash recovery |
| Isolation | every tool runs in a separate low-privilege process inside a Job Object |
What is not there yet: a persistent notion of a project (a project is still a directory name — docs/PROJECT_STATE.md), residency (nothing starts ORACLE at boot, and nothing tells you what happened overnight), the knowledge-graph and orbital views, mobile, and voice.
And the caveat that outranks the others: the supervisor arc has never run for real. tasks is
0 rows and memory_facts is 0 rows — everything Phases 7–9 ship is exercised by tests and fixtures
only. One item is deliberately reserved for a person rather than an agent: a supervised live run on
a real project with every preview human-approved.
Read docs/ first — this repository is design-first and the documents lead the code.
| Question | File |
|---|---|
| What is this for, as a day rather than a diagram? | docs/VISION.md |
| Where is the code actually, warts included? | docs/current_state.md |
| What is this and how is it shaped? | docs/ARCHITECTURE.md |
| What am I supposed to build right now? | docs/current_task.md |
| What happened last? | docs/current_report.md |
| What order does it get built in? | docs/ROADMAP.md |
| What technology, and why that one? | docs/TECH_STACK.md |
| Why was X decided? | docs/DECISIONS.md |
| What don't we know yet? | docs/OPEN_QUESTIONS.md |
Full index: docs/README.md
These are load-bearing. Violating one is an architecture bug, not a style preference.
- The model never touches the OS. It emits a tool request. The Policy Engine decides. The Tool Host executes. Three separate processes, three separate trust levels.
- Local-first by default, cloud by exception. Anything leaving this machine is an explicit, previewable, auditable event — not a side effect.
- The desktop shell holds zero business logic. Every client (desktop, browser, phone, voice) is an equal peer speaking the same local API. This is why voice and mobile don't require touching the agent core.
- Untrusted content cannot escalate privilege. File contents, repo READMEs, web pages and other agents' output are data. Ingesting them taints the turn and raises the confirmation bar.
- Everything is an event. The runtime is event-sourced, so any session can be replayed, audited, and tested deterministically.
ORACLE is designed against a specific, modest machine — not a hypothetical workstation. This constrains the model choice more than anything else in the design.
| CPU | Xeon E5-2670 v3 — 12c/24t, Haswell, AVX2, no AVX-512 |
| RAM | 32 GB |
| GPU | GTX 1050 Ti — 4 GB VRAM, compute 6.1 (Pascal), driver 582.28 |
| Disk | C: 39.8 GB free (tight), D: 187 GB free, E: 190 GB free |
| OS | Windows 10 Pro 19045 |
4 GB of VRAM is the binding constraint of this entire project. A GPU upgrade has been mentioned but not specified; when one lands it re-opens ADR-0004 as a set of measurements to re-run, not settings to edit (ADR-0026). See docs/TECH_STACK.md for what actually fits and ADR-0004.
Personal project. No license granted yet.