What Is holaOS? A Local-First AI Workstation for Persistent Agent Collaboration

holaOS is a local-first AI-powered workstation that lets you run any coding or reasoning agent inside a single shared workspace where all agents share the same persistent memory, tooling, skills, and applications.

Unlike cloud-based AI assistants that isolate each conversation or agent in silos, holaOS creates a durable, on-device environment where Claude Code, Codex, OpenAI's agents, or the built-in holaOS agent can seamlessly hand off context and continue work without reconfiguration. According to the holaboss-ai/holaOS source code, this architecture enables teams to swap agents without losing context—a critical capability for long-running development workflows【/cache/repos/github.com/holaboss-ai/holaOS/main/README.md†L9-L15】.

Core Architecture: How holaOS Works

The holaOS platform is built on six architectural pillars that together deliver persistent, cross-agent collaboration.

Shared Memory: The Semantic Knowledge Graph

At the heart of holaOS is a durable, locally-stored tree of semantic nodes. This memory system uses two distinct tree structures:

• Interaction trees: Capture conversational context and agent reasoning
• Integration trees: Store external system connections and data

Each node holds summaries as properties, while leaf nodes contain immutable evidence—raw artifacts like code snippets, documents, or API responses. This design, documented in [docs/plans/2026-05-24-memory-architecture-redesign-note.md](https://github.com/holaboss-ai/holaOS/blob/main/docs/plans/2026-05-24-memory-architecture-redesign-note.md), enables agents to recall prior work across sessions and even across different agent implementations【/cache/repos/github.com/holaboss-ai/holaOS/main/docs/plans/2026-05-24-memory-architecture-redesign-note.md†L14-L21】【/cache/repos/github.com/holaboss-ai/holaOS/main/docs/plans/2026-05-24-memory-architecture-redesign-note.md†L33-L44】.

The memory layer is queryable and editable, giving developers full ownership of their AI context.

Runtime Client: Typed API Access for Typescript

All holaOS capabilities are exposed through a unified TypeScript client defined in [packages/runtime-client/src/core.ts](https://github.com/hol aboss-ai/holaOS/blob/main/packages/runtime-client/src/core.ts). The createRuntimeClient factory returns typed namespaces:

• apps – Control HolaApps and UI surfaces
• integrations – Manage external service connections
• memory – Read and write to the semantic knowledge graph
• sessions – Track and restore agent execution contexts
• workspaces – Isolate different projects or agent runs

import { createRuntimeClient } from "@holaboss/holaOS/runtime-client";

const client = createRuntimeClient({
  baseUrl: "http://localhost:3000",
  apiKey: "YOUR_API_KEY",
});

Every namespace routes through a single request function that handles retries, timeouts, and structured error parsing【/cache/repos/github.com/holaboss-ai/holaOS/main/packages/runtime-client/src/core.ts†L1-L8】【/cache/repos/github.com/holaboss-ai/holaOS/main/packages/runtime-client/src/core.ts†L53-L66】.

State Store: SQLite-Backed Persistence

The [runtime/state-store/src/store.ts](https://github.com/holaboss-ai/holaOS/blob/main/runtime/state-store/src/store.ts) module implements the on-disk persistence layer using SQLite. It provides:

• Schema migrations for version upgrades
• Memory graph consolidation to optimize storage
• Debug CLI for inspecting stored state【/cache/repos/github.com/holaboss-ai/holaOS/main/runtime/state-store/src/store.ts†L1-L8】

This ensures your agent's memory survives restarts, crashes, and updates without corruption.

HolaApps: Real Interactive Surfaces

holaOS goes beyond chat interfaces. HolaApps are installable UI applications that live alongside agents and expose real interactive surfaces—browsers, Notion, IDEs, design tools—that agents can actually manipulate.

Agents drive these apps through the same tooling layer, enabling workflows like:

• Opening a specific Notion page
• Navigating a browser to authenticate with a service
• Editing code in a project-specific IDE configuration【/cache/repos/github.com/holaboss-ai/holaOS/main/README.md†L75-L82】

MCP: Extensible Model Context Protocol

The Model Context Protocol (MCP) is holaOS's plugin system for adding new capabilities. Through MCP servers—community-built or custom—you can extend agents with:

• New skills ( specialized coding patterns, domain knowledge)
• New integrations (proprietary APIs, internal tools)
• New model providers or reasoning strategies【/cache/repos/github.com/holaboss-ai/holaOS/main/README.md†L88-L94】

Cross-Platform Deployment Options

holaOS ships in three forms to match different security and scaling needs:

1. Electron desktop app – Single-user, fully local, offline-capable
2. Open-source self-hosted service – Team deployment on your infrastructure
3. Enterprise deployment – SSO, audit logging, and centralized administration【/cache/repos/github.com/holaboss-ai/holaOS/main/README.md†L9-L16】

Working with the holaOS Runtime Client: Code Examples

The runtime client provides a consistent interface for common operations. Below are patterns derived from the [packages/runtime-client/src/core.ts](https://github.com/holaboss-ai/holaOS/blob/main/packages/runtime-client/src/core.ts) implementation.

List and Create Workspaces

Workspaces are top-level containers that isolate different agent runs or projects:

// List existing workspaces
const wsList = await client.workspaces.list({});
console.log("Workspaces:", wsList);

// Create a fresh workspace for a new agent
const newWs = await client.workspaces.create({
  name: "my-project",
  description: "Demo workspace for a Codex run",
});

Invoke HolaApps from Agents

Agents can trigger actions in installed applications using the apps.run method:

await client.apps.run({
  appId: "notion",
  method: "openPage",
  params: { pageId: "abc123" },
});

Store and Retrieve Memories

Write structured knowledge to the persistent memory graph:

await client.memory.createLeaf({
  treeId: "integration-github-1",
  parentNodeId: "issues",
  title: "Issue #42",
  markdownBody: "# Fix bug\nDetails …",

});

All operations automatically benefit from the client's retry logic with exponential backoff and typed error contracts【/cache/repos/github.com/holaboss-ai/holaOS/main/packages/runtime-client/src/core.ts†L51-L60】.

Key holaOS Source Files for Developers

File	Purpose
[README.md](https://github.com/holaboss-ai/holaOS/blob/main/README.md)	Product overview, installation, and feature roadmap
[packages/runtime-client/src/core.ts](https://github.com/holaboss-ai/holaOS/blob/main/packages/runtime-client/src/core.ts)	Main TypeScript client with typed namespaces
[runtime/state-store/src/store.ts](https://github.com/holaboss-ai/holaOS/blob/main/runtime/state-store/src/store.ts)	SQLite persistence and debug tools
[docs/plans/2026-05-24-memory-architecture-redesign-note.md](https://github.com/holaboss-ai/holaOS/blob/main/docs/plans/2026-05-24-memory-architecture-redesign-note.md)	Memory tree design and optimization strategy
[apps/desktop/README.md](https://github.com/holaboss-ai/holaOS/blob/main/apps/desktop/README.md)	Electron app architecture and HolaApp SDK

When to Use holaOS

holaOS excels when you need:

• Agent continuity – Start with Claude Code, switch to Codex, resume with holaOS's built-in agent without re-explaining context
• Data sovereignty – Keep all AI context, credentials, and artifacts on-device or on your own infrastructure
• Real tool integration – Agents that actually operate browsers, documents, and development environments rather than just suggesting code
• Team knowledge accumulation – Shared memory graphs that grow with your codebase and processes

Summary

• holaOS is a local-first AI workstation enabling persistent, cross-agent collaboration through shared memory and tooling
• Shared Memory uses semantic trees with immutable leaf nodes to retain context across sessions and agent swaps
• Runtime Client (createRuntimeClient) provides typed, resilient access to all holaOS capabilities via unified namespaces
• State Store persists everything to SQLite with migrations and debug tooling
• HolaApps give agents real interactive surfaces to manipulate, not just APIs to call
• MCP enables extensible skills and integrations through a standardized protocol
• Deployment options range from desktop app to self-hosted service to enterprise cluster

Frequently Asked Questions

What makes holaOS different from using Claude Code or Codex directly?

Standalone agents run in isolated sessions with no memory of previous work unless you manually feed it back. holaOS creates a persistent workspace where any agent can read from and write to the same memory graph, use the same integrated tools, and resume work started by another agent. The data stays local, and you maintain full edit access to everything the AI remembers【/cache/repos/github.com/holaboss-ai/holaOS/main/README.md†L9-L15】.

Is holaOS fully open source?

Yes. The core holaOS runtime, state store, runtime client, and memory architecture are open source under the holaboss-ai organization. The project includes self-hosting instructions, and enterprise features like SSO are offered as additional deployment options rather than proprietary forks【/cache/repos/github.com/holaboss-ai/holaOS/main/README.md†L11-L16】.

How does the memory system handle large or old conversations?

The memory architecture implements consolidation in the state store layer, which optimizes the semantic tree by merging summaries and archiving or deduplicating old leaf nodes. This keeps queries fast while preserving searchable access to historical context. The design document in [docs/plans/2026-05-24-memory-architecture-redesign-note.md](https://github.com/holaboss-ai/holaOS/blob/main/docs/plans/2026-05-24-memory-architecture-redesign-note.md) details the interaction vs. integration tree split that enables this optimization【/cache/repos/github.com/holaboss-ai/holaOS/main/docs/plans/2026-05-24-memory-architecture-redesign-note.md†L33-L44】.

Can I integrate holaOS with my own internal tools?

Absolutely. The MCP (Model Context Protocol) system lets you build custom servers that expose your internal APIs, databases, or workflows as skills that any agent in holaOS can invoke. You can also use the runtime client directly to build custom orchestration logic around holaOS's core capabilities【/cache/repos/github.com/holaboss-ai/holaOS/main/README.md†L88-L94】.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}