PicoOraClaw: A local‑first AI assistant that pairs Ollama inference with Oracle AI Database–backed semantic memory
PicoOraClaw pairs a lightweight Go runtime and Ollama local inference with Oracle AI Database to provide durable, semantic memory for offline AI assistants.
A practical local‑first assistant with durable, semantic memory
PicoOraClaw is a developer‑oriented, local‑first AI assistant runtime that keeps a small footprint while giving applications durable, meaning‑based memory. The project combines a Go-based runtime and Ollama for local model inference with Oracle AI Database used as the persistent memory layer. That combination aims to let developers prototype and run private or edge assistants locally, then move the same architecture to Oracle Cloud Infrastructure (OCI) when a managed deployment is required—without rearchitecting the stack.
What PicoOraClaw is and who it targets
PicoOraClaw is a fork of PicoClaw that emphasizes a lightweight runtime, Ollama as the default local LLM backend, and Oracle AI Database for persistent memory and state. It targets use cases where local operation, a small resource footprint, and durable context are priorities: edge AI, IoT, private assistants, and local‑first developer workflows. The repository provides a developer‑friendly architecture for assistants that store sessions, transcripts, prompts, and long‑term memories and retrieve that information semantically rather than by keyword matching.
Core architecture: runtime, local inference, and database memory
The runtime is written in Go and is intentionally lightweight so it can run in resource‑constrained environments including x86_64, ARM64, and RISC‑V platforms. For inference, PicoOraClaw defaults to Ollama, enabling fully local model execution with no cloud API keys required. Oracle AI Database functions as the unified memory core: sessions, transcripts, notes, prompts, configuration and long‑term memories are stored in the database with ACID persistence.
Semantic recall happens in the database using in‑database ONNX embeddings and vector search. The assistant stores text with an ONNX embedding via VECTOR_EMBEDDING(ALL_MINILM_L12_V2 USING :text AS DATA) and retrieves relevant memories using VECTOR_DISTANCE() for cosine similarity, so the system can find meaning‑related data rather than relying on exact keywords. Because embeddings and vector search run inside the database, PicoOraClaw does not require an external embedding API.
Features that shape developer workflows
PicoOraClaw bundles several practical features for building and operating assistants:
- A lightweight Go runtime suitable for local and edge deployments.
- Oracle AI Database as the persistent memory layer for sessions, transcripts, state, notes, prompts and configuration.
- Ollama as the default local LLM backend to enable offline inference without cloud dependencies.
- Support for multiple LLM providers beyond Ollama (listed in the project): OpenRouter, Zhipu, Anthropic, OpenAI, Gemini, DeepSeek, Groq.
- A default path using Oracle AI Database Free with vector search for semantic memory and an optional Autonomous AI Database path for a managed cloud deployment.
- Graceful file‑based fallback mode if Oracle is unavailable.
- A one‑click OCI deployment option that provisions compute, Ollama, Oracle AI Database Free, and the PicoOraClaw gateway as a systemd service.
- An included oci‑genai proxy to route OpenAI‑compatible requests to OCI Generative AI as an optional backend.
- An oracle‑inspect CLI that lets operators inspect stored data without writing SQL.
Installation and developer quick start
The project provides a very quick installation path intended to get developers up and running locally. The repo includes a one‑command installer that clones, configures, and runs the app. Developers who prefer manual control can clone the Oracle DevRel repository, build the PicoOraClaw binary from the apps/picooraclaw directory, and run a small set of onboarding steps:
- Build: git clone … ; cd oracle-ai-developer-hub/apps/picooraclaw ; make build.
- Initialize: ./build/picooraclaw onboard, which creates local configuration and working directories.
- Start Ollama and pull a model (example: ollama pull qwen3:latest). Ollama is the recommended local LLM backend.
- Configure PicoOraClaw to point at your Ollama instance and model by editing ~/.picooraclaw/config.json to set provider, model, and api_base (for a local Ollama endpoint).
- Run PicoOraClaw agent (one‑shot: ./build/picooraclaw agent -m "Hello!"; interactive: ./build/picooraclaw agent) to begin local conversations.
These steps produce a working local assistant with no cloud dependency when Ollama is the model backend.
Adding Oracle AI Vector Search for durable semantic memory
To add persistent semantic memory, the project includes scripts to install and initialize an Oracle AI Database Free container and load the ONNX embedding model. A provided setup script runs the following flow:
- starts the Oracle AI Database Free container,
- waits for the database to be ready,
- creates a picooraclaw user with required privileges,
- patches ~/.picooraclaw/config.json with Oracle connection settings,
- runs picooraclaw setup‑oracle to initialize schema and load the ONNX embedding model.
When setup completes, the assistant can seed prompts into the workspace, confirm the ONNX model is present (the example shows ALL_MINILM_L12_V2), and validate VECTOR_EMBEDDING() and VECTOR_DISTANCE() functionality. With that in place, memory storage and retrieval are durable and crash‑safe via the database’s ACID transactions.
Operational visibility: oracle‑inspect and the database schema
PicoOraClaw exposes operational tools for inspecting and debugging stored data. The oracle‑inspect CLI is designed to let operators explore what the assistant stores without writing SQL. The inspector exposes tables including memories, sessions, transcripts, state, notes, prompts, config, and meta. Common inspector commands include:
- ./build/picooraclaw oracle-inspect — summary dashboard across tables and recent entries.
- ./build/picooraclaw oracle-inspect memories — list all memories.
- ./build/picooraclaw oracle-inspect memories -s "query" — perform a semantic search over memories using the database vector search.
- ./build/picooraclaw oracle-inspect sessions — inspect stored chat sessions.
- ./build/picooraclaw oracle-inspect state — inspect key‑value agent state such as last_channel, last_model and total_conversations.
The inspector’s summary output shows per‑table row counts and recent entries so developers and operators can see what is stored and how memory is being used. The ability to run semantic search directly via the inspector demonstrates that recall operates on 384‑dimensional vectors (the example uses cosine similarity) rather than exact text matching.
CLI reference and workflow primitives
PicoOraClaw provides a concise set of CLI commands that cover core workflows:
- picooraclaw onboard — initialize config and workspace.
- picooraclaw agent -m "…" — one‑shot chat.
- picooraclaw agent — interactive chat mode.
- picooraclaw setup‑oracle — initialize Oracle schema and ONNX embedding model.
- picooraclaw oracle‑inspect — inspect database contents and run semantic searches.
- picooraclaw gateway — start the long‑running service with channels enabled.
These primitives are intended to let developers run locally, test semantic memory, and operate the assistant with clear migration paths to a managed environment.
Deployment path to Oracle Cloud Infrastructure
For teams that want a managed deployment, the project includes a one‑click OCI Resource Manager stack that provisions an OCI Compute instance, Ollama with a preloaded model for CPU inference, Oracle AI Database Free by default (with an optional Autonomous AI Database path), and the PicoOraClaw gateway configured as a systemd service. After deployment, standard operational checks include tailing the setup log on the compute instance, starting interactive agents over SSH, and querying gateway health endpoints. The OCI path is presented as a seamless scaling option that preserves the original local architecture.
What PicoOraClaw does, how it works, and why it matters
PicoOraClaw provides a local runtime that:
- stores conversational state and long‑term memories in Oracle AI Database,
- embeds text with an in‑database ONNX model, and
- retrieves relevant memories by vector distance (cosine similarity), enabling semantic recall.
This approach matters because it reduces architectural complexity for projects that need both private inference and durable memory. Instead of assembling separate services for vector embeddings, a vector index, and persistence, PicoOraClaw centralizes memory and retrieval inside Oracle AI Database. That reduces the need for external embedding APIs and gives operators a single, inspectable source of truth for what the assistant remembers.
Who benefits: developers building private assistants, edge AI prototypes, IoT agents, and teams that want a clear path from local development to OCI managed deployment. The combination of Ollama and Oracle AI Database also supports privacy‑sensitive workflows by enabling fully offline inference and on‑premise or single‑tenant memory storage.
When you can use it: the project provides local and cloud deployment paths; the installer and build instructions let you run a prototype locally, and the Resource Manager stack supports one‑click deployment to OCI when you need a managed environment.
Developer implications and integrations
For developers, PicoOraClaw folds several practical integrations into one pattern:
- Local model execution with Ollama removes immediate dependence on cloud inference APIs and keys.
- The Oracle AI Database memory layer provides native ONNX embedding and vector search support, cutting out external embedding services.
- The oci‑genai proxy enables enterprises to route OpenAI‑compatible calls to OCI Generative AI when that backend is preferred.
- The oracle‑inspect CLI and the database schema tables (memories, sessions, transcripts, state, notes, prompts, config, meta) make stored context discoverable and debuggable without separate admin tooling.
These integrations make PicoOraClaw a useful reference architecture for teams combining AI models, database vector search, and lightweight runtime tooling. It also aligns with developer toolchains that rely on Go, local model experimentation, and database‑centric operational workflows.
Broader implications for AI systems and businesses
PicoOraClaw illustrates a broader pattern for assistant design: put persistent, meaning‑aware memory into a transactionally consistent datastore that also offers embedding and vector search. That pattern simplifies the service topology for memory‑dependent agents and shifts operational focus to database management and model provisioning. For businesses, particularly those with privacy, compliance, or edge constraints, this can reduce external dependencies while preserving the ability to scale into a managed cloud environment. For developers, the model encourages building assistants that are inspectable and auditable because stored memories and session artifacts are in a single, queryable system.
Operational considerations and constraints
The project’s design emphasizes a small runtime footprint, local model inference, and in‑database embeddings. It provides a file‑based fallback mode if Oracle AI Database is unavailable. The OCI deployment path offers a managed option, including an Autonomous AI Database alternative. Oracle AI Database becomes the central operational artifact: schema initialization, ONNX model loading, and vector search tests are part of setup, and operators use oracle‑inspect for visibility.
How to test semantic memory in practice
Practical memory tests demonstrated in the project include storing a fact and recalling it by meaning rather than keywords:
- Store: ./build/picooraclaw agent -m "Remember that my favorite language is Go"
- Recall: ./build/picooraclaw agent -m "What programming language do I prefer?"
The recall command finds the stored memory using cosine similarity over 384‑dimensional vectors. The oracle‑inspect CLI can also list and semantically query memories, for example: ./build/picooraclaw oracle-inspect memories -s "what does the user like to program in".
Governance, visibility, and debugging
Because memories, prompts, and state are stored in Oracle AI Database tables, operators can inspect what the assistant stores using the oracle‑inspect tool rather than crafting SQL. That improves operational transparency: memory entries, sessions, transcripts and agent state are visible in the database and in the inspector’s dashboard view. This makes it easier to audit behavior, debug retrieval mismatches, and understand how prompts and stored context influence the assistant.
Looking ahead, PicoOraClaw presents a reproducible pattern for local‑first assistants: a compact runtime for on‑device or private hosting, local model execution for offline and privacy‑sensitive use, and a single durable database for semantic memory and state. For teams that need persistence, semantic recall, and a clear migration path to OCI, PicoOraClaw packages the pieces into a working developer experience and operational model that preserves the same architecture from prototype to cloud.
