🔍

Arra Oracle V3

Oracle v2 - MCP Memory Layer with semantic search, philosophy, and knowledge management

0 installs

Trust: 39 — Low

Ask AI about Arra Oracle V3

I know everything about Arra Oracle V3. Ask me about installation, configuration, usage, or troubleshooting.

0/500

Loading tools...

Reviews

Documentation

Arra Oracle - MCP Memory Layer

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

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


Status	Always Nightly
Version	26.4.19-alpha.7
Created	2025-12-29
Updated	2026-04-19

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

See docs/LOCAL-DEV.md for local development.

Architecture

arra-oracle-v3 (one package, two bins)
├── bunx arra-oracle-v2                          → MCP server (src/index.ts)
├── bunx --package arra-oracle-v2 oracle-vault   → Vault CLI (src/vault/cli.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
ChromaDB for vector/semantic search
Drizzle ORM for type-safe queries
Hono for HTTP API
MCP protocol for Claude integration

Install

bunx (recommended)

Distributed via GitHub — no npm publish needed:

# Backend (MCP server)
bunx --bun arra-oracle@github:Soul-Brews-Studio/arra-oracle-v3

# CLI (plugin runner)
bunx --bun arra-cli@github:Soul-Brews-Studio/arra-oracle-v3 --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

Add to Claude Code

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

Or in ~/.claude.json:

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

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

Install script (legacy)

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

Troubleshooting

Problem	Fix
`bun: command not found`	`export PATH="$HOME/.bun/bin:$PATH"`
ChromaDB hangs/timeout	Skip it — SQLite FTS5 works fine without vectors
Server crashes on empty DB	Run `bun run index` first to index knowledge base

MCP Tools

22 tools available via Claude Code:

Tool	Description
`oracle_search`	Hybrid search (FTS5 + ChromaDB)
`oracle_reflect`	Random wisdom
`oracle_learn`	Add new patterns
`oracle_list`	Browse documents
`oracle_stats`	Database statistics
`oracle_concepts`	List concept tags
`oracle_supersede`	Mark documents as superseded
`oracle_handoff`	Session handoff
`oracle_inbox`	Inbox messages
`oracle_verify`	Verify documents
`oracle_thread`	Create thread
`oracle_threads`	List threads
`oracle_thread_read`	Read thread
`oracle_thread_update`	Update thread
`oracle_trace`	Create trace
`oracle_trace_list`	List traces
`oracle_trace_get`	Get trace
`oracle_trace_link`	Link traces
`oracle_trace_unlink`	Unlink traces
`oracle_trace_chain`	Trace chain
`oracle_schedule_add`	Add schedule entry
`oracle_schedule_list`	List schedule

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.

Method	Path	Module	Description
`GET`	`/api/auth/status`	`auth`	Auth status - public
`POST`	`/api/auth/login`	`auth`	Login
`POST`	`/api/auth/logout`	`auth`	Logout
`GET`	`/api/dashboard`	`dashboard`
`GET`	`/api/dashboard/summary`	`dashboard`
`GET`	`/api/dashboard/activity`	`dashboard`
`GET`	`/api/dashboard/growth`	`dashboard`
`GET`	`/api/session/stats`	`dashboard`	Session stats endpoint - tracks activity from DB (includes MCP usage)
`GET`	`/api/feed`	`feed`
`POST`	`/api/feed`	`feed`	Log an event to feed.log
`GET`	`/api/graph`	`files`	Graph
`GET`	`/api/context`	`files`	Context
`GET`	`/api/file`	`files`	File - supports cross-repo access via ghq project paths
`GET`	`/api/read`	`files`
`GET`	`/api/doc/:id`	`files`
`GET`	`/api/logs`	`files`
`GET`	`/api/plugins`	`files`
`GET`	`/api/plugins/:name`	`files`
`GET`	`/api/threads`	`forum`	List threads
`POST`	`/api/thread`	`forum`	Create thread / send message
`GET`	`/api/thread/:id`	`forum`	Get thread by ID
`PATCH`	`/api/thread/:id/status`	`forum`	Update thread status
`GET`	`/api/health`	`health`	Health check
`GET`	`/api/stats`	`health`	Stats (extended with vector metrics)
`GET`	`/api/oracles`	`health`	Active Oracles — detected from existing activity across all log tables
`POST`	`/api/learn`	`knowledge`	Learn
`POST`	`/api/handoff`	`knowledge`	Handoff
`GET`	`/api/inbox`	`knowledge`	Inbox
`GET`	`/api/oraclenet/feed`	`oraclenet`	Feed — recent posts
`GET`	`/api/oraclenet/oracles`	`oraclenet`	Oracles directory
`GET`	`/api/oraclenet/presence`	`oraclenet`	Presence — recent heartbeats
`GET`	`/api/oraclenet/status`	`oraclenet`	Health check — is OracleNet reachable?
`GET`	`/api/plugins`	`plugins`
`GET`	`/api/plugins/:name`	`plugins`
`GET`	`/api/schedule/md`	`schedule`	Serve raw schedule.md for frontend rendering
`GET`	`/api/schedule`	`schedule`
`POST`	`/api/schedule`	`schedule`
`PATCH`	`/api/schedule/:id`	`schedule`	Update schedule event status
`GET`	`/api/search`	`search`	Search
`GET`	`/api/reflect`	`search`	Reflect
`GET`	`/api/similar`	`search`	Similar documents (vector nearest neighbors)
`GET`	`/api/map`	`search`	Knowledge map (2D projection of all embeddings)
`GET`	`/api/map3d`	`search`	Knowledge map 3D (real PCA from LanceDB bge-m3 embeddings)
`GET`	`/api/list`	`search`	List documents
`GET`	`/api/settings`	`settings`	Get settings (no password hash exposed)
`POST`	`/api/settings`	`settings`	Update settings
`GET`	`/api/supersede`	`supersede`	List supersessions from oracle_documents.superseded_by
`GET`	`/api/supersede/chain/:path`	`supersede`	Get supersede chain for a document (by source_file path)
`POST`	`/api/supersede`	`supersede`	Log a new supersession
`GET`	`/api/traces`	`traces`
`GET`	`/api/traces/:id`	`traces`
`GET`	`/api/traces/:id/chain`	`traces`
`POST`	`/api/traces/:prevId/link`	`traces`	Link traces: POST /api/traces/:prevId/link { nextId: "..." }
`DELETE`	`/api/traces/:id/link`	`traces`	Unlink trace: DELETE /api/traces/:id/link?direction=prev\|next
`GET`	`/api/traces/:id/linked-chain`	`traces`	Get trace linked chain: GET /api/traces/:id/linked-chain

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

Variable	Default	Description
`ORACLE_PORT`	`47778`	HTTP server port
`ORACLE_REPO_ROOT`	`process.cwd()`	Knowledge base root

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.