# Storage

Choose JSONL or SQLite persistence for durable OrchaJS sessions.

Source: https://orcha.sh/docs/storage
Markdown: https://orcha.sh/docs/storage.mdx

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:

```ts
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`.

## JSONL

JSONL is the default and requires no configuration:

```ts

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

You can also select it explicitly:

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

Each session is an append-only file:

```text
.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.

## SQLite

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

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

The database is created automatically:

```text
.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:

```text
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 directory

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

```ts
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 SQLite

Copy existing histories before changing `storage.strategy`:

```bash
# 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:

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

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

## Export a portable session

Export one session from the currently configured adapter as JSONL:

```bash
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 data

Use [`agent.events()`](/docs/sessions/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.