Skip to content

jasperan/tinyoraclaw

BranchesTags

Repository files navigation

TinyOraClaw

TinyOraClaw

Multi-Agent AI Assistant + Oracle AI Database for Persistent Memory

TypeScript Node.js Python Oracle Database Free OCI GenAI MIT License

Deploy to Oracle Cloud

What is TinyOraClaw?

TinyOraClaw is a fork of TinyClaw that replaces all SQLite storage with Oracle AI Database as the exclusive persistence layer. Every message, conversation, and memory is stored in Oracle with in-database ONNX vector embeddings for semantic recall.

TinyClaw is a multi-agent, multi-team, multi-channel 24/7 AI assistant framework. TinyOraClaw preserves all of its capabilities while adding enterprise-grade persistence and vector search.

Architecture at a Glance

Full interactive presentation: Open tinyoraclaw-presentation.html in your browser for all 24 slides with animations and keyboard navigation.

Title
TinyOraClaw Title		 Architecture
Architecture
Team Orchestration
Teams		 7 Oracle Tables
Oracle Tables
Web Dashboard
Dashboard		 Tech Stack
Tech Stack

Why Oracle AI Database?

Feature SQLite (upstream) Oracle AI Database (TinyOraClaw)
Embeddings None In-database ONNX (VECTOR_EMBEDDING())
Semantic Search None VECTOR_DISTANCE() with COSINE similarity
Crash Recovery WAL journal Full ACID transactions
Concurrent Access File-level locking Connection pooling + row-level locking
Scalability Single-file Enterprise (FreePDB local or ADB cloud)
Audit Trail None Full transcript logging

Key Features

Everything from TinyClaw:

  • Multi-agent — Run multiple isolated AI agents with specialized roles
  • Multi-team collaboration — Agents hand off work via chain execution and fan-out
  • Multi-channel — Discord, WhatsApp, and Telegram
  • Web portal (TinyOffice) — Browser-based dashboard for chat, agents, teams, tasks, logs
  • Team Observation — Observe agent team conversations in real-time

Plus Oracle AI Database:

  • Oracle AI Database as exclusive storage backend (not SQLite, not files)
  • In-database ONNX embeddings (ALL_MINILM_L12_V2) — zero external API calls
  • Semantic memory recall — agents remember by meaning, not just keywords
  • Python FastAPI sidecar for all Oracle operations
  • Docker Compose with FreePDB (local) + ADB (cloud) modes
  • Full audit transcripts with agent attribution

Architecture

┌─────────────────────────────────────────────────┐
│  TinyClaw (TypeScript/Node.js)                  │
│  ├── Channels: Discord, Telegram, WhatsApp      │
│  ├── Hono API Server (:3777) ◄──────────┐      │
│  ├── Queue Processor                     │      │
│  └── Agent Coordination                  │ SSE  │
│           │ HTTP/REST                    │      │
│           ▼                              │      │
│  TinyOraClaw Service (Python FastAPI :8100)      │
│  ├── Message Queue API                          │
│  ├── Memory Service (VECTOR_EMBEDDING)          │
│  ├── Session Service                            │
│  ├── Transcript Service                         │
│  └── Connection Pool Manager                    │
│           │ oracledb (async)                     │
│           ▼                                      │
│  Oracle AI Database 26ai Free (:1521)           │
│  ├── TINY_MESSAGES   (queue lifecycle)           │
│  ├── TINY_RESPONSES  (delivery tracking)         │
│  ├── TINY_MEMORIES   (VECTOR(384) + COSINE)     │
│  ├── TINY_SESSIONS   (JSON CLOB history)         │
│  ├── TINY_TRANSCRIPTS (audit log)                │
│  ├── TINY_STATE      (agent K-V store)           │
│  └── TINY_META       (schema versioning)         │
├─────────────────────────────────────────────────┤
│  TinyOffice (Next.js :3000) ─────────────┘      │
│  ├── Real-time agent/team dashboard             │
│  ├── Web chat console                           │
│  ├── Kanban task board                          │
│  └── Logs & settings viewer                     │
└─────────────────────────────────────────────────┘

The tinyoraclaw-service sidecar handles all Oracle operations:

  • Connection pooling and lifecycle management
  • Schema initialization (auto-init on startup)
  • Embedding generation via VECTOR_EMBEDDING()
  • Memory store with vector similarity search
  • Session persistence (JSON CLOB)
  • Full audit transcripts

Upstream TinyClaw connects to the sidecar via HTTP/REST, replacing all SQLite calls.

Quick Start

One-command install — clone, configure, and run in a single step:

curl -fsSL https://raw.githubusercontent.com/jasperan/tinyoraclaw/main/install.sh | bash
Advanced options

Override install location:

PROJECT_DIR=/opt/myapp curl -fsSL https://raw.githubusercontent.com/jasperan/tinyoraclaw/main/install.sh | bash

Or install manually:

git clone https://github.com/jasperan/tinyoraclaw.git
cd tinyoraclaw
# See below for setup instructions

1. Clone

git clone https://github.com/jasperan/tinyoraclaw.git
cd tinyoraclaw

2. Start Oracle + Sidecar

cp .env.example .env
docker compose up oracle-db tinyoraclaw-service -d

# Wait for Oracle to become healthy (~2 minutes on first run)
docker compose logs -f oracle-db

3. Install TinyClaw

npm install
npm run build

4. Configure & Run

# Set up agents via the TinyClaw setup wizard
./tinyclaw.sh setup

# Start everything (queue, channels, heartbeat, TinyOffice dashboard)
./tinyclaw.sh start

TinyOffice launches automatically at http://localhost:3000 — open it in your browser to watch agents communicate in real time, manage teams, chat via the web console, and monitor the message queue.

To run just the queue processor standalone:

npm run queue

Docker Compose

# Full stack: Oracle + Sidecar (default)
docker compose up -d

# Oracle only (for local dev against sidecar)
docker compose up oracle-db -d

# ADB cloud mode (no local Oracle needed)
docker compose --profile adb up tinyoraclaw-service-adb -d

Oracle Schema

Table Purpose Key Feature
TINY_META Schema versioning Single row per key
TINY_MESSAGES Message queue Full lifecycle: pending → processing → completed/dead
TINY_RESPONSES Response tracking Delivery status with ack timestamps
TINY_MEMORIES Long-term memory VECTOR(384) + COSINE index for semantic recall
TINY_SESSIONS Chat history JSON CLOB per team (replaces filesystem .md)
TINY_TRANSCRIPTS Audit log Full conversation record with agent attribution
TINY_STATE Agent K-V store Composite PK (agent_id, key)

All tables support multi-agent isolation via agent_id column.

Configuration

FreePDB (Local Docker)

ORACLE_MODE=freepdb
ORACLE_HOST=localhost
ORACLE_PORT=1521
ORACLE_SERVICE=FREEPDB1
ORACLE_USER=tinyoraclaw
ORACLE_PASSWORD=TinyOraClaw2026  # pragma: allowlist secret

ADB (Oracle Cloud)

ORACLE_MODE=adb
ORACLE_USER=ADMIN
ORACLE_PASSWORD=Welcome12345*  # pragma: allowlist secret
ORACLE_DSN=(description= (retry_count=20)(retry_delay=3)...)

See .env.example for full configuration reference.

Sidecar API

The Python FastAPI sidecar exposes these endpoints on port 8100:

Endpoint Method Purpose
/api/health GET Readiness + DB connectivity
/api/init POST Manual schema initialization
/api/queue/enqueue POST Add message to queue
/api/queue/next/{agent_id} GET Claim next pending message
/api/queue/status GET Queue counts by status
/api/memory/remember POST Store memory with auto-embedding
/api/memory/recall POST Semantic vector search
/api/sessions/save POST Persist chat session
/api/sessions/{team_id} GET Load session history
/api/transcripts/log POST Write audit entry

Deploy to Oracle Cloud (One-Click)

Deploy a fully configured TinyOraClaw instance on OCI with Oracle AI Database — all automated.

Deploy to Oracle Cloud

What gets deployed:

  • OCI Compute instance (shape of your choice, ARM A1.Flex is Always Free)
  • Oracle AI Database 26ai Free container (or managed Autonomous DB)
  • TinyOraClaw Python sidecar (auto-init schema)
  • Node.js 22 with TinyClaw built and ready
  • Systemd service for the queue processor

After deployment:

ssh opc@<public-ip>
cd /opt/tinyoraclaw
./tinyclaw.sh setup        # configure agents
systemctl start tinyoraclaw-queue  # start processing

TinyOffice Dashboard

TinyOffice is a Next.js web dashboard that launches automatically with ./tinyclaw.sh start. It connects to the Hono API server via SSE for real-time updates.

URL: http://localhost:3000 (starts automatically)

Feature Description
Live Dashboard Real-time agent activity via Server-Sent Events
Web Chat Console Send messages to @agent or @team from the browser
Agent & Team Management Create, edit, and delete agents and teams
Kanban Task Board Drag-and-drop task management with agent assignment
Logs Viewer Live event stream and historical log browsing
Settings Editor Edit settings.json directly from the UI
Office View Visual simulation of agent workspace

To run TinyOffice standalone (without the full daemon):

npm run tinyoffice
# or
cd tinyoffice && npm run dev

OCI Generative AI (Optional)

TinyOraClaw can optionally use OCI Generative AI as an LLM backend via the oci-openai Python library. This is not required — the default LLM provider (Anthropic/OpenAI via API keys) works out of the box.

Why OCI GenAI?

  • Enterprise models — Access xAI Grok, Meta Llama, Cohere, and other models through OCI
  • OCI-native auth — Uses your existing ~/.oci/config profile (no separate API keys)
  • Same region as your database — Run inference and storage in the same OCI region

Setup

  1. Install the OCI GenAI client:

    cd oci-genai
pip install -r requirements.txt

  2. Configure OCI credentials (~/.oci/config):

    [DEFAULT]
user=ocid1.user.oc1..aaaaaaaaexample
fingerprint=aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99
tenancy=ocid1.tenancy.oc1..aaaaaaaaexample
region=us-chicago-1
key_file=~/.oci/oci_api_key.pem

  3. Set environment variables in your .env:

    OCI_PROFILE=DEFAULT
OCI_REGION=us-chicago-1
OCI_COMPARTMENT_ID=ocid1.compartment.oc1..your-compartment-ocid

  4. Start the OCI GenAI proxy:

    cd oci-genai
python proxy.py
# Proxy runs at http://localhost:9999/v1

  5. Point TinyOraClaw at the proxy by configuring the LLM provider to use http://localhost:9999/v1 as the base URL with any API key value.

See oci-genai/README.md for full documentation.

Sister Projects

Project Upstream Language Description
OracLaw OpenClaw TypeScript + Python Code-aware AI with Oracle memory
PicoOraClaw PicoClaw Go Lightweight agent with Oracle storage
ZeroOraClaw ZeroClaw Rust High-performance agent with Oracle backend
TinyOraClaw TinyClaw TypeScript + Python Multi-agent teams with Oracle persistence
IronOraClaw IronClaw Rust Secure AI assistant with Oracle backend

License

MIT License — see LICENSE for details.

Based on TinyClaw by Jian Liao.

GitHub  LinkedIn  Oracle

About

Multi-Agent AI Assistant + Oracle AI Database for Persistent Memory (fork of TinyClaw)

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages