Arra Oracle V3 — Docker-first MCP Memory + Search

— Vercel quickstart

Docker run → arra mine ~/notes → open the UI → search your memory.

Arra Oracle is the Oracle family's local memory and search layer. It stores your notes in SQLite, searches them with FTS/vector-capable APIs, and exposes the same memory through HTTP, MCP, the arra CLI, plugins, and the Studio UI.

Quick start: Docker is the primary path

You only need Docker, curl, and a notes folder. This path starts the HTTP server, mines ~/notes, opens the built-in UI, and performs the first search. No local Bun install, API key, schema choice, or vector service is required.

1. Run Arra Oracle

export ARRA_PORT="${ARRA_PORT:-47778}"
export ARRA_URL="http://127.0.0.1:${ARRA_PORT}"
export ARRA_CONTAINER="${ARRA_CONTAINER:-arra-oracle}"
export ARRA_VOLUME="${ARRA_VOLUME:-arra-oracle-data}"
export ARRA_NOTES_DIR="${ARRA_NOTES_DIR:-$HOME/notes}"

mkdir -p "$ARRA_NOTES_DIR"
docker volume create "$ARRA_VOLUME" >/dev/null

docker run --rm -d --name "$ARRA_CONTAINER" \
  -p "${ARRA_PORT}:47778" \
  -v "${ARRA_VOLUME}:/data" \
  -v "${ARRA_NOTES_DIR}:${ARRA_NOTES_DIR}:ro" \
  ghcr.io/soul-brews-studio/arra-oracle-v3:http

until curl -sf "${ARRA_URL}/api/health" >/dev/null; do sleep 1; done
echo "Arra Oracle is ready: ${ARRA_URL}"

If port 47778 is busy, run export ARRA_PORT=47878 first. If your notes live somewhere else, set ARRA_NOTES_DIR=/path/to/notes before docker run.

2. Mine your notes

Use the CLI bundled inside the running container so ingestion writes to the same Docker volume as the server:

arra() {
  docker exec "$ARRA_CONTAINER" bun dist-cli/index.js "$@"
}

arra mine ~/notes

Re-running arra mine is safe: unchanged Markdown, MDX, and text files are skipped with deterministic IDs. If you pointed ARRA_NOTES_DIR somewhere else, run arra mine "$ARRA_NOTES_DIR".

3. Open the UI

Open Simple Mode in your browser:

echo "${ARRA_URL}/simple"

Simple Mode shows health, save/search actions, and links to advanced surfaces.

4. Search

Use the UI search box, or call the HTTP API directly:

curl -sfS "${ARRA_URL}/api/v1/search?q=runbook&mode=fts&limit=5"

For grounded answers with citations:

curl -sfS "${ARRA_URL}/api/v1/ask" \
  -H 'content-type: application/json' \
  -d '{"q":"What did I write about runbooks?","limit":5,"llm":false}'

"llm": false keeps the answer extractive and local.

Stop, restart, or inspect

curl -sf "${ARRA_URL}/api/health"
docker logs "$ARRA_CONTAINER"
docker stop "$ARRA_CONTAINER"

Restart later by re-running the docker run block. Your memory remains in the Docker volume named by $ARRA_VOLUME.

MCP clients with Docker

Use the stdio image when a desktop or agent needs Oracle MCP tools. It can share the same Docker volume as the HTTP server:

claude mcp add arra-oracle -- docker run --rm -i \
  -e ORACLE_LOG_TARGET=stderr \
  -v "${ARRA_VOLUME:-arra-oracle-data}:/data" \
  ghcr.io/soul-brews-studio/arra-oracle-v3:stdio

claude mcp list

The MCP surface includes Oracle search, read, learn, recap, profile, research note, trace, and tool-catalog capabilities.

What ships

Architecture at a glance

Notes / agents / browsers / MCP clients
        │
        ├── Docker HTTP: ghcr.io/...:http on :47778
        ├── Docker stdio MCP: ghcr.io/...:stdio
        ├── CLI: arra mine/search/learn/export
        └── Studio and Simple Mode UI
                  │
        Elysia routes + MCP tools + plugin registry
                  │
        SQLite + FTS + optional vector stores + local vault files

The design goal is one memory core with thin adapters. CLI, HTTP, MCP, plugins, canvas, and web/desktop surfaces reuse shared contracts instead of duplicating business logic.

Source development path

Use a local checkout only when editing Arra Oracle itself:

git clone https://github.com/Soul-Brews-Studio/arra-oracle-v3.git
cd arra-oracle-v3
bun install
bunx tsc --noEmit
bun run server

Then open http://localhost:47778/simple or call http://localhost:47778/api/v1/search?q=oracle&mode=fts.

Useful checks before a PR:

bunx tsc --noEmit
bun test tests/http/<cluster>/
bun test tests/docs/link-checker.test.ts

Work targets alpha; never push or merge directly to main. Keep source, test, and docs files at or below 250 lines.

More docs

• 10-minute Docker quickstart

• Docker MCP Toolkit

• HTTP API reference

• Plugin quickstart

• DigitalOcean Docker deploy

• Local development

• Docs index

• Changelog

License

Arra Oracle V3 is licensed under BUSL-1.1. See LICENSE.

Acknowledgments

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