Arra Oracle

CI License CalVer Bun

"The Oracle Keeps the Human Human" - now queryable via MCP

Phukhao Oracle is landing here: https://phukhao.buildwithoracle.com/presentation/

TypeScript MCP server for semantic search over Oracle philosophy — SQLite FTS5 + LanceDB hybrid search, HTTP API, and vault CLI.

See docs/LOCAL-DEV.md for local development. For Docker MCP Toolkit / Gateway / n8n installs, see docs/DOCKER-MCP-TOOLKIT.md. For the progressive first-run path from zero-config FTS to MCP, indexing, vectors, and audit logs, see docs/ONBOARDING.md.

Architecture

arra-oracle-v3 (one package, two primary bins + legacy aliases)
├── bunx --package github:Soul-Brews-Studio/arra-oracle-v3 arra-oracle  → HTTP API (bin/arra.ts)
├── bunx --package github:Soul-Brews-Studio/arra-oracle-v3 arra-cli     → operator CLI (cli/src/cli.ts)
├── bunx --package github:Soul-Brews-Studio/arra-oracle-v3 arra-oracle-v2 → legacy MCP alias (src/index.ts)
├── bun run server                                                       → HTTP API (src/server.ts)
└── bun run index                                                        → Indexer (src/indexer.ts)

oracle-studio (separate repo)
└── bunx oracle-studio                      → React dashboard

Stack:

• Bun runtime (>=1.2.0)
• SQLite + FTS5 for full-text search
• LanceDB for vector/semantic search
• Drizzle ORM for type-safe queries
• Hono for HTTP API
• MCP protocol for Claude integration

Progressive onboarding

Arra now starts with a low-friction floor and lets you opt into heavier pieces only when ready:

1. Install and search immediately — start the HTTP server and use SQLite FTS5 via GET /api/search?mode=fts&q=.... A fresh install works without vector indexes; hybrid/vector requests degrade to FTS until vectors are ready (#1370).
2. Connect MCP with a small tool surface — add the stdio MCP server, then trim exposed tools through config (.arra/config.json, ORACLE_ENABLED_TOOLS, ORACLE_DISABLED_TOOLS) or the /tools/config page backed by GET/PUT /api/settings/tools (#1372/#1373).
3. Save deploy credentials in the browser — /connect stores ORACLE_API plus optional ARRA_API_TOKEN, can generate a token for your server env, and renders claude mcp add / JSON snippets (#1374).
4. Index your ψ vault — when a repo has ψ/, scan with POST /api/indexer/scan and populate SQLite/FTS with POST /api/indexer/reindex (#1375).
5. Enable vectors when ready — choose local engine/model with GET/PATCH /api/vector/config, index vectors with POST /api/vector/index/start, or move vector work behind VECTOR_URL; GET /api/health reports vectorMode (embedded, proxied, disabled) once #1390 lands (#1377/#1390).
6. Review what the AI searched — /traces reads GET /api/logs plus GET /api/traces / GET /api/traces/:id, including AI-search audit details so searches are inspectable (#1384).

Detailed walkthrough: docs/ONBOARDING.md.

Install

bunx (recommended)

Distributed via GitHub — no npm publish needed:

# HTTP server
bunx --bun --package github:Soul-Brews-Studio/arra-oracle-v3 arra-oracle

# CLI (operator client)
bunx --bun --package github:Soul-Brews-Studio/arra-oracle-v3 arra-cli --help

# UI (dashboard — separate repo)
bunx --bun oracle-studio@github:Soul-Brews-Studio/oracle-studio

# Vault CLI (secondary bin — use --package)
bunx --bun --package arra-oracle-v2@github:Soul-Brews-Studio/arra-oracle-v3#main oracle-vault --help

Canonical bins are arra-oracle (server) and arra-cli (client). Legacy aliases arra-oracle-v3 and arra-oracle-v2 stay available for existing installs, Docker commands, and MCP configs. See docs/BINS.md.

Add to Claude Code

claude mcp add arra-oracle-v2 -- bunx --bun --package github:Soul-Brews-Studio/arra-oracle-v3 arra-oracle-v2

Or in ~/.claude.json:

{
  "mcpServers": {
    "arra-oracle-v2": {
      "command": "bunx",
      "args": ["--bun", "--package", "github:Soul-Brews-Studio/arra-oracle-v3", "arra-oracle-v2"]
    }
  }
}

For a canonical install that shares ORACLE_DATA_DIR with Codex / the HTTP API (and gives pinned-commit control + offline starts), see Oracle 101 — ch03 "ติดตั้งจาก 0". §3.11 note: if both Claude Code and Codex are installed, they MUST point at the same ORACLE_DATA_DIR.

From source

git clone https://github.com/Soul-Brews-Studio/arra-oracle-v3.git
cd arra-oracle-v3 && bun install
bun run dev          # MCP server
bun run server       # HTTP API on :47778

curl -sSL https://raw.githubusercontent.com/Soul-Brews-Studio/arra-oracle-v3/main/scripts/install.sh | bash

MCP Tools

23 tools available via Claude Code:

Vault CLI

Global CLI for managing the Oracle knowledge vault:

oracle-vault init <owner/repo>    # Initialize vault with GitHub repo
oracle-vault status               # Show config and pending changes
oracle-vault sync                 # Commit + push to GitHub
oracle-vault pull                 # Pull vault files into local ψ/
oracle-vault migrate              # Seed vault from ghq repos

API Endpoints

HTTP API on port 47778 (bun run server).

Auto-generated by bun run scripts/gen-endpoints.ts. 55 endpoints across 14 modules.

Database

Drizzle ORM with SQLite:

bun db:push       # Push schema to DB
bun db:generate   # Generate migrations
bun db:migrate    # Apply migrations
bun db:studio     # Open Drizzle Studio GUI

Project Structure

arra-oracle-v3/
├── src/
│   ├── index.ts          # MCP server entry
│   ├── server.ts         # HTTP API (Hono)
│   ├── indexer.ts        # Knowledge indexer
│   ├── vault/
│   │   └── cli.ts        # Vault CLI entry
│   ├── tools/            # MCP tool handlers
│   ├── trace/            # Trace system
│   ├── db/
│   │   ├── schema.ts     # Drizzle schema
│   │   └── index.ts      # DB client
│   └── server/           # HTTP server modules
├── scripts/              # Setup & utility scripts
├── docs/                 # Documentation
└── drizzle.config.ts     # Drizzle configuration

Configuration

Testing

bun test              # All tests
bun test:unit         # Unit tests
bun test:integration  # Integration tests
bun test:e2e          # Playwright E2E tests
bun test:coverage     # With coverage

New awakenings welcome

Awakening a new Oracle? Post the birth announcement and experience report to Discussions, not Issues. See docs/CONTRIBUTING-AWAKENING.md for categories and signature convention.

References

• TIMELINE.md - Full evolution history
• docs/API.md - API documentation
• docs/architecture.md - Architecture details
• docs/CONTRIBUTING-AWAKENING.md - Where to post awakening announcements
• Drizzle ORM
• MCP SDK

Acknowledgments

Inspired by claude-mem by Alex Newman — process manager pattern, worker service architecture, and hook system concepts.