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
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.
