Oracle

Agents forget. Projects drift. Every new session starts by re-reading the same files, re-deriving the same conclusions, and quietly trusting whatever the last summary happened to say.

Oracle gives long-running AI work a shared source of truth that can explain itself. One rule: ask before you investigate, write back what you learn. Facts, reviewed Claims, open Questions, conflicts, and hypotheses carry across sessions — each with provenance, freshness, and a trust tier you can inspect.

In practice

An agent is about to dig into "how does auth work?" It asks Oracle first:

oracle_ask({ question: "how does auth work?" })

→ known · verified · fresh
  "Sessions are stateless JWTs; refresh lives in the edge worker, not the API."
  provenance: file.grep over auth/*.ts · checked 2 days ago · anchor still fresh

It uses the answer and moves on — no re-investigation. Had Oracle replied not_known, the agent would investigate, then write the result back with evidence so the next session starts from truth instead of guessing:

oracle_tell({
  claim: "Refresh tokens are rotated by the edge worker, not the API",
  subject: "auth-refresh",
  predicate: "architecture",
  evidence: [{ kind: "fileAnchor", path: "edge/worker.ts", startLine: 40, endLine: 72 }]
})

The anchor is pinned to the real bytes of edge/worker.ts. Change that file and the fact goes stale on the next read — trust drops automatically, no one has to remember to invalidate it.

flowchart TD
    A["Agent observes"] --> B["Claim + provenance"]
    B --> C["Oracle ledger"]
    C --> D["Trust status<br/>production Fact / Claim / Question"]
    C --> E["Provenance<br/>who said it, when, and why"]
    C --> F["Freshness<br/>still true, stale, or orphaned"]
    C --> G["Conflicts<br/>surfaced instead of buried"]
    D --> H["Next agent asks first"]
    E --> H
    F --> H
    G --> H

Oracle is for cooperating agents on a single host or trusted workspace. It is evidence-gated and conflict-aware, but it is not a multi-tenant authorization service and should not be exposed to untrusted clients.

Built For

Oracle is built for agents that aim to work long hours on complex projects, where losing the thread is expensive and guessing from stale context is worse.

| When agents are... | Oracle helps them... | |---|---| | debugging across days | keep repro facts separate from theories | | researching messy systems | preserve sourced findings and unresolved claims | | handing off work | start from evidence, not a summary vibe | | preparing releases | carry blockers, sign-offs, risks, and caveats | | reviewing complex code | surface conflicts instead of burying them | | returning after compaction | rebuild context from durable project truth |

Core Features

Six things Oracle does that plain scratch memory does not:

| Feature | Why it matters | |---|---| | Ask-first memory | Agents check what is already known before re-investigating. | | Trust status | Facts, Claims, and Questions expose explicit trust and admission state. | | Provenance receipts | Every important node can explain where it came from. | | Freshness checks | Code-linked facts lose trust when the underlying file changes. | | Conflict surfacing | Contradictions become visible work instead of silent drift. | | Warm-start briefs | New sessions get facts, gaps, conflicts, and stale assumptions upfront. |

See DEMO.md for a short transcript.

Tools At A Glance

The MCP surface agents actually call — ask first, write back, resolve conflicts:

| Tool family | What agents use it for | |---|---| | oracle_ask | Ask what the project already knows before spending time investigating. | | oracle_tell | Write back an observation. In signed v2 this proposes a Claim; production Facts require producer or typed-attestation admission. | | oracle_brief | Start or resume with top facts, gaps, stale anchors, and open conflicts. | | oracle_explain | Inspect Fact proof/trust state, Claim or Question status, provenance, history, and conflicts. | | oracle_changes | Watch for source-of-truth updates without treating notifications as facts. | | oracle_health / oracle_stats | Check ledger, index, compaction, and store health before relying on memory. | | oracle_propose_* / oracle_review_* / oracle_admit_* | Turn claims and questions into reviewed project truth instead of solo assertions. | | oracle_run_producer | Compatibility producer runner; signed-v2 production producer Facts use retained producer.run.v2 signed commands. |

For exact schemas and payload details, see docs/TOOLS.md.

Install

As a Claude Code plugin (recommended)

The fastest path. From inside Claude Code:

/plugin marketplace add adammcarter/oracle
/plugin install oracle@adammcarter

That registers the oracle MCP server (run via npx @adammcarter/oracle), the SessionStart bootstrap, and the setup + workflow skills in one step. The server uses your project directory as ORACLE_ROOT_DIR automatically. Node.js 20.19+ must be on your PATH.

As a global npm package

npm install -g @adammcarter/oracle

Then wire it into any MCP host (see Configure an MCP host).

From source

git clone https://github.com/adammcarter/oracle.git
cd oracle
npm install
npm run build      # → dist/
npm test
npm run demo

Configure an MCP host

For a source checkout:

{
  "mcpServers": {
    "oracle": {
      "command": "node",
      "args": ["/ABS/PATH/TO/oracle/dist/index.js"],
      "env": {
        "ORACLE_ROOT_DIR": "/ABS/PATH/TO/your/project",
        "ORACLE_TRUST_MODE": "unsigned-dev",
        "ORACLE_SCOPE": "your-project",
        "ORACLE_LOG_PATH": "/ABS/PATH/TO/your/project/.oracle/oracle.jsonl"
      }
    }
  }
}

For a global npm install, use "command": "oracle" and omit args.

| Env var | Default | Purpose | |---|---|---| | ORACLE_ROOT_DIR | cwd | Base dir for file anchors and absolute-scope safety checks. | | ORACLE_LOG_PATH | <root>/.oracle/oracle.jsonl | The append-only event log (git-diffable; commit it to share project truth). | | ORACLE_SCOPE | basename of root | Default scope for tell/ask. | | ORACLE_AGENT | mcp-client | Provenance agent name. | | ORACLE_TRUST_MODE | unsigned-dev | unsigned-dev for local trusted agents; signed requires a keyring. | | ORACLE_KEYRING_PATH | unset | Required when ORACLE_TRUST_MODE=signed. | | ORACLE_RECOVERY_ROOT_PUBLIC_KEY_B64 | unset | Signed-v2 recovery-root public key used by operator repair validation. | | ORACLE_PENDING_CLAIM_LIMIT | 4096 | Maximum live pending claims accepted before new claim proposals are rejected. Same-content pending claim re-proposals are idempotent and do not append another ledger event. | | ORACLE_PENDING_QUESTION_LIMIT | 4096 | Maximum live pending questions accepted before new question proposals are rejected. | | ORACLE_ANCHOR_STORE_BACKEND | unset | Signed-v2 anchor backend. Only file is supported (the local file anchor); may be left unset. The prior cloud/DynamoDB backend was removed, so any other value (e.g. a stale dynamodb) now fails startup. | | ORACLE_ANCHOR_STORE_PATH | unset | Local file anchor path. Enables the anchor when set (and selects the file backend). |

Agent Bootstrap And Skills

Oracle ships guidance so agents actually use it well, not just have it available.

• SessionStart bootstrap. For hosts that support SessionStart hooks, Oracle ships concise high-priority guidance in bootstrap/using-oracle.md. The hook wrapper in hooks/session-start injects it inside <EXTREMELY_IMPORTANT> without calling Oracle, writing facts, or creating project state. It only nudges: use Oracle as durable project truth, not scratch memory. Global npm installs register the bootstrap for Claude Code, Codex, Copilot CLI, and OpenCode unless hook installation is disabled.
• Skills. Installing the plugin also ships three on-demand skills:
  • oracle-setup-greenfield — stand Oracle up in a new project.
  • oracle-setup-retrofit — adopt Oracle into an existing repo and backfill its durable truth without dumping noise.
  • oracle-workflow — the day-to-day ask-first / write-back / resolve-conflicts discipline, pulled in while you work.

Prefer to hand-write the agent instruction instead of using the hook? See the optional docs/CONSULT-FIRST-RULE.md, and the full docs/ORACLE-AGENT-GUIDE.md for every tool.

How Trust Works

Oracle treats trust as a feature, not a promise in prose. It is explicit about what the server checks, what it preserves for audit, and what still depends on a trusted local workspace.

Evidence and tiers

Ordinary signed-v2 write-back creates Claims; production Facts require registered producer output or typed attestations over pinned subject material and active policy.

| Tier | What it means | How it is earned | |---|---|---| | verified | Production-verifiable evidence backs the Fact. | In signed v2, an admitted Fact from a registered producer or typed attestation over pinned input and active policy. Legacy/unsigned paths may expose compatibility labels, but not production verification. | | inferred | Strong but not fully checkable. | Derived from evidence that supports the claim without proving it directly. | | hypothesis | Useful lead, not established truth. | A working theory an agent wants future sessions to test. | | secondhand | Reported but soft. | Human or agent reports without machine-checkable proof. |

| Freshness state | Effect | |---|---| | fresh | The anchor still matches the file bytes Oracle checked. | | stale | The linked code changed, so trust drops one tier at read time. | | orphaned | The anchor no longer resolves, so the fact reads as secondhand. |

Reads never mutate the log; effective trust is recomputed when agents ask.

What Oracle verifies

| Trust feature | Built-in behavior | Outside the boundary | |---|---|---| | Server-checked file anchors | Re-hashes real file bytes and re-checks freshness on every read. | Audit/provenance material by itself; signed-v2 production Facts still require producer or typed-attestation admission. | | Caller-supplied command/test receipts | Records captured output and exit status so agents can inspect the proof trail. | Audit material by itself; the server does not re-execute receipts or treat them as production verification. | | Producer and typed-attestation admission | Admits production Facts only from registered deterministic producers or typed attestations under active policy. | Requires configured policy, authority, and pinned subject material. | | Append-only event log | Preserves provenance and folds current state from history. | Raw filesystem writers can still forge internally coherent lines. | | Schema-hardened ingestion | Rejects malformed or incoherent records instead of crashing or trusting stored flags. | This is integrity hardening, not a replacement for OS/file permissions. | | Single-host write lock | Coordinates local cooperating agents. | Do not expose Oracle to untrusted clients without an external auth boundary. |

Export boundary

Current federation exports are explicitly non-authoritative. Per-node credentials can authenticate exported payloads, but they do not prove an accepted ledger head, complete projection, current trust policy, or undegraded state. Production imports must treat them as attestation or claim input unless they are re-admitted through local producer or attestation rules.

Operator Admin CLI

Advanced / optional. The default unsigned-dev setup needs none of this. Skip the whole section unless you are running signed-v2 operator workflows.

oracle-admin is a local operator binary, not an MCP tool. In signed-v2 mode it drives local administrative workflows with the same ORACLE_* environment as the server:

oracle-admin repair preflight --proposal repair-proposal.json
oracle-admin repair execute --input repair-input.json
oracle-admin repair audits
oracle-admin migration preflight --source legacy.jsonl --source-ledger-id legacy-ledger:id
oracle-admin migration verify --records materialized-records.json --expected-digest <hex64>
oracle-admin migration authorize --root-public-key-file root-public.b64 --root-private-key-file root-private.b64 --migration preflight.json
oracle-admin migration sign --authorization authorize.json --principal-id operator --key-id operator-key --auth-sequence 1 --request-id request-cutover --private-key-file operator-private.b64
oracle-admin migration execute --command signed-cutover-command.json
oracle-admin sidecar preflight --keyring signed-keyring.json
oracle-admin sidecar demote --keyring signed-keyring.json --root-signature <signature-b64>

repair-proposal.json contains newSegment and anchorTransition. repair-input.json contains those fields plus a recovery-root-signed manifest. migration preflight validates an Oracle v1 JSONL legacy source and emits the migration binding for a separately authorized final trust.cutover.v2 / trust_model.activated payload; it does not append to the ledger. migration verify re-checks a materialized legacy record set (a JSON array of records) against the exact importedProjectionDigest a cutover is to be authorized over: it normalizes and projects the records, fails closed on any schema/projection diagnostic, and exits 0 with {ok:true, digest, recordCount} only when the recomputed digest matches — an independent, service-free pre-sign audit gate for the operator or an offline approver. migration authorize derives the live cutover identity from the verified signed prefix and attaches the external-governance-root authorization proof. migration sign turns that authorization output into a signed trust.cutover.v2 command envelope without constructing the service. migration execute is the only mutating migration command: it accepts only a signed trust.cutover.v2 command file and applies it through the normal signed-command commit path. sidecar preflight verifies an operator-root-signed sidecar keyring and emits the reduced ledger-writer-only entries with the canonical bytes and digest the operator root must sign; sidecar demote emits the demoted keyring only when supplied a fresh root signature over those reduced entries. Neither sidecar command constructs the service or appends to the ledger. Ordinary MCP clients do not get repair/root-key/import operations.

Security And Release

For reporting vulnerabilities, see SECURITY.md. For public release steps, see docs/RELEASE.md.

License

MIT.