Storage

Orcha persists every session as an ordered stream of events. The storage adapter changes where those events live, but it does not change the agent API:

await orcha.supportAgent.get(sessionId);
await orcha.supportAgent.history(sessionId);
await orcha.supportAgent.events(sessionId);
await orcha.supportAgent.list();

Choose the adapter in orcha/index.ts.

JSONLCopy Anchor Link

JSONL is the default and requires no configuration:

import { orcha } from "orchajs";

orcha.init({
  providers: {
    openai: process.env.OPENAI_API_KEY ?? "",
  },
  agents: {
    supportAgent: "./supportAgent",
  },
});

You can also select it explicitly:

storage: {
  strategy: "node-jsonl",
}

Each session is an append-only file:

.orcha/sessions/<agentName>/<sessionId>.jsonl

Each line contains one complete event. JSONL is useful when you want the smallest local setup, easy inspection with normal text tools, or one portable file per session.

SQLiteCopy Anchor Link

SQLite stores every agent's sessions in one project-level database:

orcha.init({
  storage: {
    strategy: "sqlite",
  },
  providers: {
    openai: process.env.OPENAI_API_KEY ?? "",
  },
  agents: {
    supportAgent: "./supportAgent",
  },
});

The database is created automatically:

.orcha/sessions/orcha-sqlite.db

Orcha includes the native SQLite driver as an internal optional dependency. Applications do not configure or import the driver themselves. Package-manager installations must not omit optional dependencies when SQLite is selected.

SQLite stores one event per row and separates histories by agent name, session ID, and event sequence. It provides transactional writes, indexed access, and safer coordination between concurrent readers and writers.

While SQLite is active, you may also see:

orcha-sqlite.db-wal
orcha-sqlite.db-shm

These are normal SQLite write-ahead-log and shared-memory files. Do not delete or copy them individually while Orcha is running. SQLite tools and GUI clients should open the main orcha-sqlite.db file.

Custom storage directoryCopy Anchor Link

Both adapters use .orcha/sessions by default. Change the parent directory with storage.directory:

storage: {
  strategy: "sqlite",
  directory: ".data/orcha",
}

SQLite then writes .data/orcha/orcha-sqlite.db; JSONL writes its per-agent session files below .data/orcha/.

Switch between JSONL and SQLiteCopy Anchor Link

Copy existing histories before changing storage.strategy:

# Copy JSONL histories into SQLite.
npx orcha migrate-storage --to sqlite

# Copy SQLite histories back into JSONL.
npx orcha migrate-storage --to node-jsonl

The migration does not delete the source. It is safe to repeat when the destination contains the same history; Orcha appends only missing events and rejects conflicting histories.

Migrate one agent only:

npx orcha migrate-storage --to sqlite --agent supportAgent

After migration, update storage.strategy and restart the application.

Export a portable sessionCopy Anchor Link

Export one session from the currently configured adapter as JSONL:

npx orcha export-session supportAgent ses_123 --output session.jsonl

This is useful for debugging, transfer, and archival without exposing the underlying database schema.

Inspect stored dataCopy Anchor Link

Use agent.events() for application code. It works with both adapters and keeps your application independent of physical storage.

For local inspection:

• JSONL can be opened directly in a text editor.
• SQLite can be opened with a SQLite extension for Cursor/VS Code, DB Browser for SQLite, TablePlus, or another SQLite client.

Treat .orcha/ as runtime data: do not edit it manually, commit it, or expose it publicly.