{"_id":"@adammcarter/oracle","_rev":"2-2241391c89a0dad174c37b4a1102e919","name":"@adammcarter/oracle","dist-tags":{"latest":"0.3.0"},"versions":{"0.2.0":{"name":"@adammcarter/oracle","version":"0.2.0","keywords":["mcp","model-context-protocol","oracle","knowledge-base","evidence","agents"],"license":"MIT","_id":"@adammcarter/oracle@0.2.0","maintainers":[{"name":"adammcarter","email":"adamcarter93@icloud.com"}],"homepage":"https://github.com/adammcarter/oracle#readme","bugs":{"url":"https://github.com/adammcarter/oracle/issues"},"bin":{"oracle":"dist/index.js","oracle-admin":"dist/admin.js"},"dist":{"shasum":"f64deef2d39748fdad28c2f479bbc06eaf606c87","tarball":"https://registry.npmjs.org/@adammcarter/oracle/-/oracle-0.2.0.tgz","fileCount":772,"integrity":"sha512-4JxbLGoKobyNSkl15KNdGUpRB/6UMEsWdVaK4MlrwCbm72S2+Ee8F95Ze0juCXoioygYtIzmmwDInAR5EjUiMw==","signatures":[{"sig":"MEQCIFvfEmYfgGZbCZacfExni65JTs3382Yn1HUpRqryJzbiAiAxk0vedXyUvSfqg1R71UC0w/HL9reycyQdlZkmHdp6UA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":3865181},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20.19.0"},"gitHead":"41955556073266cbc8f8af5fa21f619133df5807","mcpName":"io.github.adammcarter/oracle","scripts":{"dev":"tsx src/index.ts","demo":"tsx scripts/demo.ts","test":"vitest run","build":"npm run clean && tsc -p tsconfig.build.json","clean":"node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"","start":"node dist/index.js","prepack":"npm run build","pack:dry":"npm pack --dry-run","typecheck":"tsc --noEmit","test:watch":"vitest","acceptance:v2-local":"node scripts/mcp-harness.mjs V2T23 V2T36 V2T38 V2T46 V2T47 V2T67 V2T68 V2T68SIGNER V2T70","acceptance:v2-local-all":"npm run build && node scripts/mcp-harness.mjs V2T23 V2T36 V2T38 V2T46 V2T47 V2T67 V2T68 V2T68SIGNER V2T70 && node scripts/v2-external-signer-local-acceptance.mjs","acceptance:v2-external-signer-local":"npm run build && node scripts/v2-external-signer-local-acceptance.mjs"},"_npmUser":{"name":"adammcarter","email":"adamcarter93@icloud.com"},"repository":{"url":"git+https://github.com/adammcarter/oracle.git","type":"git"},"_npmVersion":"11.17.0","description":"Oracle is a trust-tiered shared knowledge store for AI agents, separating Claims and Questions from producer or attestation-backed Facts with provenance, conflicts, freshness, and health checks.","directories":{},"_nodeVersion":"26.4.0","dependencies":{"zod":"^4.4.3","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.22.4","vitest":"^4.1.9","fast-check":"^4.8.0","typescript":"^5.9.3","@types/node":"^22.20.0"},"_npmOperationalInternal":{"tmp":"tmp/oracle_0.2.0_1783113856669_0.1989978819443725","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@adammcarter/oracle","version":"0.3.0","mcpName":"io.github.adammcarter/oracle","description":"Oracle is a trust-tiered shared knowledge store for AI agents, separating Claims and Questions from producer or attestation-backed Facts with provenance, conflicts, freshness, and health checks.","type":"module","main":"dist/index.js","bin":{"oracle":"dist/index.js","oracle-admin":"dist/admin.js"},"repository":{"type":"git","url":"git+https://github.com/adammcarter/oracle.git"},"homepage":"https://github.com/adammcarter/oracle#readme","bugs":{"url":"https://github.com/adammcarter/oracle/issues"},"engines":{"node":">=20.19.0"},"scripts":{"clean":"node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"","build":"npm run clean && tsc -p tsconfig.build.json","dev":"tsx src/index.ts","prepack":"npm run build","postinstall":"node scripts/install-agent-hooks.mjs","pack:dry":"npm pack --dry-run","start":"node dist/index.js","test":"vitest run","test:watch":"vitest","typecheck":"tsc --noEmit","demo":"tsx scripts/demo.ts","acceptance:v2-local":"node scripts/mcp-harness.mjs V2T23 V2T36 V2T38 V2T46 V2T47 V2T67 V2T68 V2T68SIGNER V2T70","acceptance:v2-local-all":"npm run build && node scripts/mcp-harness.mjs V2T23 V2T36 V2T38 V2T46 V2T47 V2T67 V2T68 V2T68SIGNER V2T70 && node scripts/v2-external-signer-local-acceptance.mjs","acceptance:v2-external-signer-local":"npm run build && node scripts/v2-external-signer-local-acceptance.mjs"},"keywords":["mcp","model-context-protocol","oracle","knowledge-base","evidence","agents"],"license":"MIT","dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","zod":"^4.4.3"},"devDependencies":{"@types/node":"^22.20.0","fast-check":"^4.8.0","tsx":"^4.22.4","typescript":"^5.9.3","vitest":"^4.1.9"},"gitHead":"5a203e5c58aed1462f304c8c69692780989d2261","types":"./dist/index.d.ts","_id":"@adammcarter/oracle@0.3.0","_nodeVersion":"24.18.0","_npmVersion":"11.18.0","dist":{"integrity":"sha512-8zvG0t9qLauG5lHeoBSknG/xr61jr4TtxTyt0doJrMgS6YHYiy/PKdPoqIRMVmFtoJOgxd4i95bO/s83EvALbQ==","shasum":"ea8ba8bee5010d02c1072d0d382ab675cc099fa3","tarball":"https://registry.npmjs.org/@adammcarter/oracle/-/oracle-0.3.0.tgz","fileCount":780,"unpackedSize":3900045,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCU7DHCBTOGmm5/yYkshsgfRrwPCgjYqdsySWcK0MezJwIgeoEUZOaFY5YUKyec0R+3tymtbM4pq+dISBESJ0dwu2U="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:d75c4af0-759a-401b-825b-820a16d11299"}},"directories":{},"maintainers":[{"name":"adammcarter","email":"adamcarter93@icloud.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/oracle_0.3.0_1783469152324_0.3242650153725182"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-03T21:24:16.477Z","modified":"2026-07-08T00:05:52.700Z","0.2.0":"2026-07-03T21:24:16.837Z","0.3.0":"2026-07-08T00:05:52.490Z"},"bugs":{"url":"https://github.com/adammcarter/oracle/issues"},"license":"MIT","homepage":"https://github.com/adammcarter/oracle#readme","keywords":["mcp","model-context-protocol","oracle","knowledge-base","evidence","agents"],"repository":{"type":"git","url":"git+https://github.com/adammcarter/oracle.git"},"description":"Oracle is a trust-tiered shared knowledge store for AI agents, separating Claims and Questions from producer or attestation-backed Facts with provenance, conflicts, freshness, and health checks.","maintainers":[{"name":"adammcarter","email":"adamcarter93@icloud.com"}],"readme":"# Oracle\n\n**Agents forget. Projects drift.** Every new session starts by re-reading the\nsame files, re-deriving the same conclusions, and quietly trusting whatever the\nlast summary happened to say.\n\nOracle gives long-running AI work a shared source of truth that can explain\nitself. One rule: **ask before you investigate, write back what you learn.**\nFacts, reviewed Claims, open Questions, conflicts, and hypotheses carry across\nsessions — each with provenance, freshness, and a trust tier you can inspect.\n\n## In practice\n\nAn agent is about to dig into *\"how does auth work?\"* It asks Oracle first:\n\n```text\noracle_ask({ question: \"how does auth work?\" })\n\n→ known · verified · fresh\n  \"Sessions are stateless JWTs; refresh lives in the edge worker, not the API.\"\n  provenance: file.grep over auth/*.ts · checked 2 days ago · anchor still fresh\n```\n\nIt uses the answer and moves on — no re-investigation. Had Oracle replied\n`not_known`, the agent would investigate, then write the result back with\nevidence so the *next* session starts from truth instead of guessing:\n\n```text\noracle_tell({\n  claim: \"Refresh tokens are rotated by the edge worker, not the API\",\n  subject: \"auth-refresh\",\n  predicate: \"architecture\",\n  evidence: [{ kind: \"fileAnchor\", path: \"edge/worker.ts\", startLine: 40, endLine: 72 }]\n})\n```\n\nThe anchor is pinned to the real bytes of `edge/worker.ts`. Change that file and\nthe fact goes `stale` on the next read — trust drops automatically, no one has to\nremember to invalidate it.\n\n```mermaid\nflowchart TD\n    A[\"Agent observes\"] --> B[\"Claim + provenance\"]\n    B --> C[\"Oracle ledger\"]\n    C --> D[\"Trust status<br/>production Fact / Claim / Question\"]\n    C --> E[\"Provenance<br/>who said it, when, and why\"]\n    C --> F[\"Freshness<br/>still true, stale, or orphaned\"]\n    C --> G[\"Conflicts<br/>surfaced instead of buried\"]\n    D --> H[\"Next agent asks first\"]\n    E --> H\n    F --> H\n    G --> H\n```\n\nOracle is for cooperating agents on a single host or trusted workspace. It is\nevidence-gated and conflict-aware, but it is **not** a multi-tenant authorization\nservice and should not be exposed to untrusted clients.\n\n## Built For\n\nOracle is built for agents that aim to work long hours on complex projects,\nwhere losing the thread is expensive and guessing from stale context is worse.\n\n| When agents are... | Oracle helps them... |\n|---|---|\n| debugging across days | keep repro facts separate from theories |\n| researching messy systems | preserve sourced findings and unresolved claims |\n| handing off work | start from evidence, not a summary vibe |\n| preparing releases | carry blockers, sign-offs, risks, and caveats |\n| reviewing complex code | surface conflicts instead of burying them |\n| returning after compaction | rebuild context from durable project truth |\n\n## Core Features\n\nSix things Oracle does that plain scratch memory does not:\n\n| Feature | Why it matters |\n|---|---|\n| Ask-first memory | Agents check what is already known before re-investigating. |\n| Trust status | Facts, Claims, and Questions expose explicit trust and admission state. |\n| Provenance receipts | Every important node can explain where it came from. |\n| Freshness checks | Code-linked facts lose trust when the underlying file changes. |\n| Conflict surfacing | Contradictions become visible work instead of silent drift. |\n| Warm-start briefs | New sessions get facts, gaps, conflicts, and stale assumptions upfront. |\n\nSee [DEMO.md](./DEMO.md) for a short transcript.\n\n## Tools At A Glance\n\nThe MCP surface agents actually call — ask first, write back, resolve conflicts:\n\n| Tool family | What agents use it for |\n|---|---|\n| `oracle_ask` | Ask what the project already knows before spending time investigating. |\n| `oracle_tell` | Write back an observation. In signed v2 this proposes a Claim; production Facts require producer or typed-attestation admission. |\n| `oracle_brief` | Start or resume with top facts, gaps, stale anchors, and open conflicts. |\n| `oracle_explain` | Inspect Fact proof/trust state, Claim or Question status, provenance, history, and conflicts. |\n| `oracle_changes` | Watch for source-of-truth updates without treating notifications as facts. |\n| `oracle_health` / `oracle_stats` | Check ledger, index, compaction, and store health before relying on memory. |\n| `oracle_propose_*` / `oracle_review_*` / `oracle_admit_*` | Turn claims and questions into reviewed project truth instead of solo assertions. |\n| `oracle_run_producer` | Compatibility producer runner; signed-v2 production producer Facts use retained `producer.run.v2` signed commands. |\n\nFor exact schemas and payload details, see [docs/TOOLS.md](./docs/TOOLS.md).\n\n## Install\n\n### As a Claude Code plugin (recommended)\n\nThe fastest path. From inside Claude Code:\n\n```text\n/plugin marketplace add adammcarter/oracle\n/plugin install oracle@adammcarter\n```\n\nThat registers the `oracle` MCP server (run via `npx @adammcarter/oracle`), the\nSessionStart bootstrap, and the setup + workflow skills in one step. The server\nuses your project directory as `ORACLE_ROOT_DIR` automatically. Node.js 20.19+\nmust be on your PATH.\n\n### As a global npm package\n\n```bash\nnpm install -g @adammcarter/oracle\n```\n\nThen wire it into any MCP host (see [Configure an MCP host](#configure-an-mcp-host)).\n\n### From source\n\n```bash\ngit clone https://github.com/adammcarter/oracle.git\ncd oracle\nnpm install\nnpm run build      # → dist/\nnpm test\nnpm run demo\n```\n\n### Configure an MCP host\n\nFor a source checkout:\n\n```json\n{\n  \"mcpServers\": {\n    \"oracle\": {\n      \"command\": \"node\",\n      \"args\": [\"/ABS/PATH/TO/oracle/dist/index.js\"],\n      \"env\": {\n        \"ORACLE_ROOT_DIR\": \"/ABS/PATH/TO/your/project\",\n        \"ORACLE_TRUST_MODE\": \"unsigned-dev\",\n        \"ORACLE_SCOPE\": \"your-project\",\n        \"ORACLE_LOG_PATH\": \"/ABS/PATH/TO/your/project/.oracle/oracle.jsonl\"\n      }\n    }\n  }\n}\n```\n\nFor a global npm install, use `\"command\": \"oracle\"` and omit `args`.\n\n| Env var | Default | Purpose |\n|---|---|---|\n| `ORACLE_ROOT_DIR` | `cwd` | Base dir for file anchors and absolute-scope safety checks. |\n| `ORACLE_LOG_PATH` | `<root>/.oracle/oracle.jsonl` | The append-only event log (git-diffable; commit it to share project truth). |\n| `ORACLE_SCOPE` | basename of root | Default scope for `tell`/`ask`. |\n| `ORACLE_AGENT` | `mcp-client` | Provenance agent name. |\n| `ORACLE_TRUST_MODE` | `unsigned-dev` | `unsigned-dev` for local trusted agents; `signed` requires a keyring. |\n| `ORACLE_KEYRING_PATH` | unset | Required when `ORACLE_TRUST_MODE=signed`. |\n| `ORACLE_RECOVERY_ROOT_PUBLIC_KEY_B64` | unset | Signed-v2 recovery-root public key used by operator repair validation. |\n| `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. |\n| `ORACLE_PENDING_QUESTION_LIMIT` | `4096` | Maximum live pending questions accepted before new question proposals are rejected. |\n| `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. |\n| `ORACLE_ANCHOR_STORE_PATH` | unset | Local file anchor path. Enables the anchor when set (and selects the `file` backend). |\n\n## Agent Bootstrap And Skills\n\nOracle ships guidance so agents actually use it well, not just have it available.\n\n- **SessionStart bootstrap.** For hosts that support SessionStart hooks, Oracle\n  ships concise high-priority guidance in\n  [`bootstrap/using-oracle.md`](./bootstrap/using-oracle.md). The hook wrapper in\n  [`hooks/session-start`](./hooks/session-start) injects it inside\n  `<EXTREMELY_IMPORTANT>` without calling Oracle, writing facts, or creating\n  project state. It only nudges: use Oracle as durable project truth, not scratch\n  memory. Global npm installs register the bootstrap for Claude Code, Codex,\n  Copilot CLI, and OpenCode unless hook installation is disabled.\n- **Skills.** Installing the plugin also ships three on-demand skills:\n  - `oracle-setup-greenfield` — stand Oracle up in a new project.\n  - `oracle-setup-retrofit` — adopt Oracle into an existing repo and backfill its\n    durable truth without dumping noise.\n  - `oracle-workflow` — the day-to-day ask-first / write-back / resolve-conflicts\n    discipline, pulled in while you work.\n\nPrefer to hand-write the agent instruction instead of using the hook? See the\noptional [docs/CONSULT-FIRST-RULE.md](./docs/CONSULT-FIRST-RULE.md), and the full\n[docs/ORACLE-AGENT-GUIDE.md](./docs/ORACLE-AGENT-GUIDE.md) for every tool.\n\n## How Trust Works\n\nOracle treats trust as a feature, not a promise in prose. It is explicit about\nwhat the server checks, what it preserves for audit, and what still depends on a\ntrusted local workspace.\n\n### Evidence and tiers\n\nOrdinary signed-v2 write-back creates Claims; production Facts require registered\nproducer output or typed attestations over pinned subject material and active\npolicy.\n\n| Tier | What it means | How it is earned |\n|---|---|---|\n| `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. |\n| `inferred` | Strong but not fully checkable. | Derived from evidence that supports the claim without proving it directly. |\n| `hypothesis` | Useful lead, not established truth. | A working theory an agent wants future sessions to test. |\n| `secondhand` | Reported but soft. | Human or agent reports without machine-checkable proof. |\n\n| Freshness state | Effect |\n|---|---|\n| `fresh` | The anchor still matches the file bytes Oracle checked. |\n| `stale` | The linked code changed, so trust drops one tier at read time. |\n| `orphaned` | The anchor no longer resolves, so the fact reads as `secondhand`. |\n\nReads never mutate the log; effective trust is recomputed when agents ask.\n\n### What Oracle verifies\n\n| Trust feature | Built-in behavior | Outside the boundary |\n|---|---|---|\n| 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. |\n| 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. |\n| 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. |\n| Append-only event log | Preserves provenance and folds current state from history. | Raw filesystem writers can still forge internally coherent lines. |\n| 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. |\n| Single-host write lock | Coordinates local cooperating agents. | Do not expose Oracle to untrusted clients without an external auth boundary. |\n\n### Export boundary\n\nCurrent federation exports are explicitly non-authoritative. Per-node\ncredentials can authenticate exported payloads, but they do not prove an\naccepted ledger head, complete projection, current trust policy, or undegraded\nstate. Production imports must treat them as attestation or claim input unless\nthey are re-admitted through local producer or attestation rules.\n\n## Operator Admin CLI\n\n> **Advanced / optional.** The default `unsigned-dev` setup needs none of this.\n> Skip the whole section unless you are running signed-v2 operator workflows.\n\n`oracle-admin` is a local operator binary, not an MCP tool. In signed-v2\nmode it drives local administrative workflows with the same `ORACLE_*`\nenvironment as the server:\n\n```bash\noracle-admin repair preflight --proposal repair-proposal.json\noracle-admin repair execute --input repair-input.json\noracle-admin repair audits\noracle-admin migration preflight --source legacy.jsonl --source-ledger-id legacy-ledger:id\noracle-admin migration verify --records materialized-records.json --expected-digest <hex64>\noracle-admin migration authorize --root-public-key-file root-public.b64 --root-private-key-file root-private.b64 --migration preflight.json\noracle-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\noracle-admin migration execute --command signed-cutover-command.json\noracle-admin sidecar preflight --keyring signed-keyring.json\noracle-admin sidecar demote --keyring signed-keyring.json --root-signature <signature-b64>\n```\n\n`repair-proposal.json` contains `newSegment` and `anchorTransition`.\n`repair-input.json` contains those fields plus a recovery-root-signed\n`manifest`. `migration preflight` validates an Oracle v1 JSONL legacy source\nand emits the `migration` binding for a separately authorized final\n`trust.cutover.v2` / `trust_model.activated` payload; it does not append to the\nledger. `migration verify` re-checks a materialized legacy record set (a JSON\narray of records) against the exact `importedProjectionDigest` a cutover is to\nbe authorized over: it normalizes and projects the records, fails closed on any\nschema/projection diagnostic, and exits `0` with `{ok:true, digest,\nrecordCount}` only when the recomputed digest matches — an independent,\nservice-free pre-sign audit gate for the operator or an offline approver.\n`migration authorize` derives the live cutover identity from the verified\nsigned prefix and attaches the external-governance-root authorization proof.\n`migration sign` turns that authorization output into a signed\n`trust.cutover.v2` command envelope without constructing the service.\n`migration execute` is the only mutating migration command: it accepts only a\nsigned `trust.cutover.v2` command file and applies it through the normal\nsigned-command commit path. `sidecar preflight` verifies an operator-root-signed sidecar keyring\nand emits the reduced ledger-writer-only entries with the canonical bytes and\ndigest the operator root must sign; `sidecar demote` emits the demoted keyring\nonly when supplied a fresh root signature over those reduced entries. Neither\nsidecar command constructs the service or appends to the ledger. Ordinary MCP\nclients do not get repair/root-key/import operations.\n\n## Security And Release\n\nFor reporting vulnerabilities, see [SECURITY.md](./SECURITY.md).\nFor public release steps, see [docs/RELEASE.md](./docs/RELEASE.md).\n\n## License\n\nMIT.\n","readmeFilename":"README.md"}