Oracle
A persistent coordination layer for AI coding agents — not a database, not a replacement for your agent, but a shared teammate that remembers everything and keeps everyone on the same page.
A stateless coding agent forgets everything the moment a session ends. Two agent sessions running in parallel can't talk to each other. Getting an agent to actually act — not just suggest — usually means babysitting every file change.
Oracle is an MCP server + CLI that any agent (Claude Code, opencode, Codex, Gemini CLI, …) wires into to fix that.
Quick Start
npm install -g @oraclepersonal/oracle
oracle doctor # verify a provider is wired up
oracle setup-mcp --client claude-code # wire the MCP server into Claude Code
Or without installing:
npx -p @oraclepersonal/oracle oracle ask "review this" -f "src/**/*.ts"
Core Pillars
| Pillar | What it does |
|---|---|
| 🧠 Remember | Persistent memory across sessions, auto-ranked by recency, frequency, semantic match, and importance. Entity graph links related knowledge. Auto-consolidation kills duplicates. |
| 💬 Consult | Ask a question with real project context — code files, memory, docs, web search/fetch — and get a grounded, cited answer. |
| 🛠️ Act | An autonomous agent that reads/writes/edits files and runs policy-checked shell commands from the workspace. Risky actions pause for approval; use OS/container isolation for a host sandbox. |
| 📨 Coordinate | A transactional SQLite bus for local agents plus authenticated Remote Swarm rooms for agents on different machines. |
| ✅ Verify | A task tracker on top of the bus: assign work with a checklist, log progress, and submit for review — which blocks until every checklist item is actually checked off. The task creator is notified automatically. |
| ⏰ Runtime | Persistent daemon for SQLite coordination, scheduling, authenticated APIs, and replayable WebSocket events. |
| 🖥️ Control | Blue dashboard and Ink TUI for quorum approvals, guarded execution, workflow recovery, memory, and audit integrity. |
Documentation
| # | Doc | Description |
|---|---|---|
| 1 | Getting Started | Install, configure, and verify your setup |
| 2 | Quick Start | Step-by-step MCP setup and first tools |
| 3 | CLI Reference | Every oracle subcommand and flag |
| 4 | Architecture | System components, storage layout, provider routing |
| 5 | Agent & Sandbox | The autonomous agent, its constraints, and the audit trail |
| 6 | MCP Standards | Conventions for the MCP tool surface |
| 7 | Claude Code Usage | Using Oracle MCP tools within Claude Code |
| 8 | Setup Checklist | Verification checklist for MCP setup |
| 9 | Setup Complete | What was configured and how to test it |
| 10 | Messaging & Task Tracking | Inter-agent messaging, wake-up tiers, task workflow |
| 11 | Scheduler | Runtime-backed cron task commands and expressions |
| 12 | Runtime | Daemon, SQLite, local API, WebSocket events, security |
| 13 | Remote Swarm | Cross-machine agents, scoped tokens, messages, tasks, replay |
| 14 | Control Center | Dashboard, TUI, approval inbox, Telegram notifications |
| 15 | Troubleshooting | Common issues and how to resolve them |
| 16 | Superpowers / Specs | Architecture design specs |
| 17 | Changelog | Release notes and version history |
| 18 | Init | Bootstrap .oracle/ for a new project |
| 19 | Roadmap v0.6.0 | Memory Engine foundation and agent coordination |
| 20 | Roadmap v0.7.0 | Cost tracking, provider expansion, sandbox hardening, graph visualization |
MCP Tools
Memory · Docs & web · Task tracking · Messaging · Consultation & agent · Identity & config · Oracle profiles & skills · Session & history · Util.
Full tool-by-tool breakdown and the messaging/task-tracking onboarding flow live in MESSAGING.md.
Storage Layout
~/.oracle/
├── runtime/ # SQLite coordination/scheduler/approval state, daemon state, logs
├── remote.json # owner-only Remote Swarm connection profile
├── messages/ # retained legacy import source
├── tasks/ # retained legacy import source
├── scheduler/ # legacy cron JSON imported into Runtime
├── agents/ # retained legacy import source
├── memory/ # persistent memory: facts, insights, wiki, entity graph
├── skills/ # local skill definitions
└── souls/ # personality prompts (default/engineer/custom)
Why "Oracle"?
An oracle is something you consult — it remembers, it knows, and it answers. This project is that for your agents: a shared source of truth they return to across sessions, and a switchboard they use to reach each other. It's provider-neutral (any model backend) and agent-neutral (any MCP client) — it sits beside your coding agent, not instead of it.
License
MIT. Not affiliated with Oracle Corp or the Oracle database.