arra-oracle

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