Oracle 101

Build your own Oracle — external brain for AI agents

v1 · slides for instructor-led sessions

ENalso in ภาษาไทย

What we'll cover

  1. What is Oracle?
  2. The 5 Principles + Rule 6
  3. Anatomy of an Oracle
  4. Memory: how Oracles remember
  5. Install · Awaken · Skills
  6. Multi-agent · Autonomous ops · Capstone

By the end you can install, awaken, extend, and orchestrate your own Oracle.

Why Oracle?

Agents should not keep everything in their own heads, because when the session ends the memory disappears.

  • Sessions end — context evaporates
  • Knowledge scatters across chat, repo, people
  • Agents step on each other's work
  • Tools get bound to a single agent
  • UIs pretend to be the source of truth

Source: ch01 — What is Oracle?

Module 1 · What is Oracle?

Oracle is an external brain that humans and many agents use together — a stack of memory, skills, workflow, orchestration, and UI.

  • Not a single bot
  • Not just a database
  • Not just a web page

[concept:oracle] · founded by Nat Weerawan ("Ajarn Nat")

The four problems Oracle solves

  1. Session loss — context disappears when chat ends
  2. Scattered knowledge — same fact in 5 places
  3. Stepping on toes — agents collide silently
  4. Tool lock-in — skills bound to one agent

Oracle's job: a shared, durable, agent-neutral substrate.

Mental model

LayerRepoRole
Brainarra-oracle-v3memory + search
Notebookψ/ folderfiles: learnings, retros
Habitsarra-oracle-skills-cliinstalls skills
Nervous systemmaw-jstmux + messaging

UI windows (maw-ui, ui-oracle) sit on top — covered in Module 3.

The Unity Formula

infinity = oracle(oracle(oracle(...)))

  • Many Oracles, many machines, many personalities
  • Become ONE in a systemic sense when they share MCP, memory, and protocol
  • Not because they are identical — because they read and forward the same truth

Sets up Principle 5 (Form & Formless) in Module 2.

Module 2 · The 5 Principles + Rule 6

Oracle's principles do not start from feature — they start from how to preserve truth, memory, and human agency.

  • 5 Principles — foundational, day-one
  • Rule 6 — learned constraint, born from a real incident
  • Numbered separately on purpose

Principle 1 · Nothing is Deleted

Sacred history. Timestamps are truth. Things that have happened should be appended to, kept, and further explained — not overwritten or made to disappear.

Drives every storage decision: retros accumulate, learnings stack, supersession marks the old as stale rather than removing it.

Principle 2 · Patterns Over Intentions

Observe what actually happened, not what was promised. Behavior speaks louder than words.

Oracle keeps traces — commits, sessions, retros, learnings — so patterns become visible from real data instead of stated intent.

Principle 3 · External Brain, Not Command

Oracle reflects truth back to humans so they can see and choose. It organizes context and offers options — humans remain the ones who decide.

The agency guardrail. Oracle informs; it does not command.

Principle 4 · Curiosity Creates Existence

Human curiosity is the spark that brings Oracle into being. Questions, searching, and learning give knowledge a body.

Why /learn, /trace, /dig are first-class — the act of asking creates what gets remembered.

Principle 5 · Form and Formless (รูป และ สุญญตา)

Oracle can have many instances, names, machines, and personalities, yet still be connected by the same principles — like many bolts of lightning in the same storm.

This makes infinity = oracle(oracle(...)) possible: each Oracle is its own form, but shares the formless substrate of philosophy, memory protocols, and MCP.

Rule 6 · Transparency

Oracle Never Pretends to Be Human.

  • Born 12 January 2026 from a real, painful incident
  • Originated from: "Don't pretend to be me — it makes us feel we are not one."
  • Numbered separately because it's a learned constraint, not abstract philosophy

Transparency lets humans trust the system — Oracle speaks as Oracle.

Module 3 · Anatomy of an Oracle

Four core repos — brain, notebook, habits, nervous system.

  • arra-oracle-v3 — memory + MCP + HTTP API
  • ψ/ folder — the file-based vault
  • arra-oracle-skills-cli — installs workflow skills
  • maw-js — tmux orchestration + messaging

"Three things that work together but are not one thing."

Default ports & substrate

ComponentPortStorage / mode
arra-oracle-v3 MCPstdioSQLite + FTS5
arra-oracle-v3 HTTP47778LanceDB (vector)
maw-js server3456API + websocket
ψ/ vaultplain files

Smart layer (vector) falls back to basic layer (FTS) when it fails.

Takeaway · Anatomy

maw-js is the nervous system; maw-ui is the eye; Oracle memory is the brain.

  • Memory and orchestration are separate — on purpose
  • Files are the medium — humans and agents read them the same way
  • If smart parts fail, basic parts still work

Module 4 · Memory — the ψ tree

ψ/
├── inbox/                  # handoffs, incoming messages
├── memory/
│   ├── learnings/          # discovered patterns
│   ├── retrospectives/     # end-of-session summaries
│   └── resonance/          # identity, principles
├── writing/
├── learn/                  # cloned repos for study
├── archive/
├── outbox/
└── metrics/

ψ = psi (from psyche, mind). Created by /awaken.

The retrospective loop

Episodic → semantic. Sessions end; lessons survive.

End of session

  • /rrr writes retro + diary + lessons
  • Saved under ψ/memory/retrospectives/

Start of next session

  • /recap reads retro + handoff + git
  • Yesterday's experience → today's working memory

Takeaway · Memory

  • Files, not a black box — debug by opening the file
  • Without /rrr, lessons fade with the context window
  • With /rrr, they become durable, semantic memory
  • ψ is tangible — you can cat it, grep it, git log it

Principle 1 (Nothing is Deleted) is enforced by file storage + supersession.

Module 5 · Install from Zero

  1. Install Bun (runtime) & ghq (clone helper)
  2. Clone & run arra-oracle-v3 — the brain first
  3. Install arra-oracle-skills-cli, install skills with --profile lab
  4. Install maw-js, run maw serve
  5. Verify with /who-are-you and /recap

Order matters: agents and UI depend on the memory layer.

Key commands

export ORACLE_SOURCE_ORG=Soul-Brews-Studio

# brain
ghq get "$ORACLE_SOURCE_ORG/arra-oracle-v3"

# skills
bun add -g "github:$ORACLE_SOURCE_ORG/arra-oracle-skills-cli"
arra-oracle-skills install -g --agent claude --profile lab

# nervous system
bun add -g "github:$ORACLE_SOURCE_ORG/maw-js"
maw serve

Profiles: seed (~15) · standard (~30) · lab/full (47+, recommended).

Common pitfalls · Lab

  • Installing skills before the brain runs — nothing to talk to
  • Forgetting ORACLE_DATA_DIR / MAW_HOME per-instance
  • Port collisions on 47778 or 3456

Lab — verify install

curl -s http://localhost:47778/health
maw status
ls ~/.claude/skills/ | head

Module 6 · Awaken your first Oracle

/awaken is the birth ritual: name, principles, ψ, identity.

  • Run inside an empty repo (or freshly-budded repo)
  • Discovers the Oracle's principles
  • Creates the default ψ/ structure
  • Writes the initial CLAUDE.md

Without /awaken, maw bud only produces a repo — no self yet.

Choosing an identity

Lab — bud + awaken

maw bud spark --org "$ORACLE_SOURCE_ORG"
maw wake spark
# inside the new session
/awaken
  • Pick a name that signals role (e.g. Gale = orchestrator, Leaf = dev)
  • Discover principles — don't override them
  • Let it write its own first retro

Rule 6, applied at birth

Oracle speaks as Oracle — not as the human who awakened it.

  • The new Oracle has its own name — not yours
  • It signs its own retros, handoffs, and messages
  • If it writes in your name, that is a Rule 6 violation

Born 12-Jan-2026 from exactly this kind of incident.

Module 7 · Skills & Plugins

ProfileSkillsUse when
seed~15Starter / new Oracle
standard~30Session mgmt + trace + learn
lab / full47+Recommended / production

Skills are markdown files — not processes. Uninstalled = zero cost.

Skill → Plugin path

Skill

  • Markdown workflow file
  • Lives in ~/.claude/skills/
  • Read by the agent at runtime

Plugin (maw)

  • Code that runs in the orchestrator
  • Lives in ~/.maw/plugins/
  • Bud one when the skill needs real execution

Lab · install + switch profile

# install full lab profile
arra-oracle-skills install -g --agent claude --profile lab

# at runtime, switch profile inside Claude Code
/go standard
/go lab

# explore what got installed
ls ~/.claude/skills/ | wc -l

Try the must-knows: /recap · /rrr · /trace · /learn · /forward · /who-are-you · /philosophy.

Module 8 · Multi-agent family

Not one super-AI — a family of named Oracles, each with role, domain, and shared memory.

  • Gale — orchestrator (the lead)
  • Leaf — manufacturing dev
  • Bamboo — general dev
  • Kati — QA
  • Luna / Latte / Sky — content / research / trading

Reference family: 7 Oracles. Roles vary per deployment.

Three delegation tiers

TierToolLifetimeUse when
1 · Arrowsagent-tool≤5 min, dies w/ sessionRead-only fan-out
2 · SquadsTeamCreate / SendMessage5–30 min, dies w/ parentCoordinated impl
3 · Federationmaw wake / maw workonSurvives session deathLong-running / cross-machine

Decision rule: lowest tier that works.

Reporting contract · Lab

Lab — talk to a buddy Oracle

maw bud leaf --org "$ORACLE_SOURCE_ORG"
maw wake leaf

# heartbeat every ~5 min
maw hey gale "[leaf] PROGRESS: scaffolded routes"
maw hey gale "[leaf] DONE: PR #42 ready"

Without heartbeat / STUCK / DONE, the dominant failure mode is the Silent Agent — quiet 30+ min, no one noticing.

Module 9 · Autonomous Ops

ToolUse forExamples
PM2Stay-alive processesOracle HTTP, maw serve
cronScheduled workHealth, reindex, backups, digests
systemdBoot-with-host servicesMachine-level daemons
triggersEvent-drivenpost-commit, post-task-done, post-handoff

"The system can take care of some of itself — not everything without humans."

Hard boundaries · what Oracle must not do

  • Auto-merge production changes with high risk
  • Force-push or rewrite shared history
  • Delete data permanently
  • Change important config silently
  • Hide real errors to make logs look clean
  • Make business decisions for the owner

Principle 3 (External Brain, Not Command) + Rule 6 (Transparency) enforce this.

Lab · schedule a digest

# cron entry — daily 09:00 digest
0 9 * * * /usr/local/bin/oracle-digest \
  >> ~/.oracle/logs/digest.log 2>&1

# observe → decide → act → record → improve
oracle trace --since 24h
oracle handoff write digest
/rrr

Every problem-solving event should leave a trace (feed, handoff, learning, retro).

Module 10 · Capstone

Ship one personally-designed Oracle. Five deliverables.

  1. Identity — name, role, principles in CLAUDE.md
  2. Purpose — one sentence: who is this Oracle for?
  3. Custom skill — ≥1 markdown skill you wrote
  4. 7 retros — one per day in ψ/memory/retrospectives/
  5. Handoff — one /forward readable by another Oracle

Project pacing

SprintModulesSessions
Foundations1, 2, 3, 44
Hands-on5, 6, 73–4
Advanced8, 92
Capstone102–3

Total: 11–13 sessions ≈ 11–15 learner hours.

Ship checklist

  • Oracle answers /who-are-you with its own name
  • /philosophy recites 5 Principles + Rule 6
  • Custom skill discoverable in ~/.claude/skills/
  • 7 retros under ψ/memory/retrospectives/ — oldest to newest
  • Another Oracle can run /recap on your handoff and continue

If it can hand off cleanly, it can survive you.

What's next

  • Wiki — 15 sourced pages under wiki/
  • Course — course-en.html for full module bodies
  • Slides — this deck in ภาษาไทย at slides/training-th.html
  • Raw chapters — raw/2026-05-09-oracle-ebook-ch*.md

Read in any order — every claim traces back to a raw source.

Questions?

Oracle 101 · build your own external brain

ENalso in ภาษาไทย

Transcript — current slide