Concurrency

What is it?

Wolbarg 0.4 hardens multi-process writers against a single SQLite memory.db — the topology most multi-agent setups use (one Node process or worker per agent, one shared file).

Before 0.4, SQLite mutating paths used deferred BEGIN. Under concurrent writers that commonly produced SQLITE_BUSY at commit time after work had already started. 0.4 acquires the write lock up front and retries with backoff when the lock is contended.

Guarantees

PostgreSQL is unchanged for this feature — it already uses row-level locking and connection pooling. Concurrency config is ignored on the Postgres provider.

Why it matters for agents

Multi-agent frameworks often open the same SQLite file from several processes:

• Parallel tool workers writing preferences / facts
• Dev servers + background jobs sharing local memory
• CLI agents launched side-by-side against one project DB

Without write-lock discipline, you get intermittent failures, orphaned retries, or corrupted mental models when agents silently drop writes. Wolbarg 0.4 makes contention visible, retryable, and bounded.

Configuration

import { wolbarg, openaiEmbedding } from "wolbarg";

const ctx = wolbarg({
  organization: "my-org",
  database: { provider: "sqlite", url: "./memory.db" },
  embedding: openaiEmbedding({
    apiKey: process.env.OPENAI_API_KEY!,
    model: "text-embedding-3-small",
  }),
  concurrency: {
    maxRetries: 5,       // default — app-level retry attempts after SQLITE_BUSY
    baseBackoffMs: 50,   // default — first backoff floor
    maxBackoffMs: 2000,  // default — backoff ceiling
    lockTimeoutMs: 5000, // SQLite busy_timeout pragma (ms)
  },
});

Defaults are conservative for a handful of concurrent agent processes. Raise maxRetries / lockTimeoutMs for bursty writers; switch to Postgres when you need high fan-out multi-tenant write throughput.

Defaults

How it works (internals)

1. A mutating path (remember, update, forget, ingest writes, compress archive, …) opens a transaction with BEGIN IMMEDIATE.
2. If another process holds the write lock, SQLite returns busy within lockTimeoutMs.
3. Wolbarg sleeps with exponential backoff + jitter and retries up to maxRetries.
4. If all attempts fail, it throws WOLBARG_STORAGE_LOCKED — not a generic SQLite string.
5. Same-process callers also queue through an in-process mutex so Node async concurrency does not pile on top of OS-level lock storms.

Tradeoffs

Tune for your workload, or move shared multi-tenant agents to the PostgreSQL backend.

Errors

Suggestion text on the error points at the same remediation.

Benchmarks

Same-process stress (v4 suite)

Published dual-backend v0.4 stress numbers (SQLite · Postgres):

Mock embeddings; Node v24 · win32/arm64 · 8 CPUs · generated 2026-07-18. Absolute ops/sec vary by machine.

Multi-process levels

True multi-process writers (separate OS processes, shared SQLite file):

npx tsx benchmark/multiprocess-levels.ts

Artifact: /benchmarks/multiprocess-concurrency.json — levels 2 / 5 / 10 / 20 writers with throughput, p50/p95/p99, error rate, and integrity checks. At 20 writers this run held 0% error rate with integrity OK (p95 rises as expected under serialization).

Interactive charts: /benchmarks. Methodology: Benchmarks.

When to use Postgres instead

Choose PostgreSQL when:

• Many agents share one cluster across hosts
• You need cross-process real-time events (LISTEN/NOTIFY)
• Write fan-out regularly exceeds what a single SQLite file can serialize comfortably

Related pages

• Real-time events
• SQLite · PostgreSQL
• Benchmarks
• What's New in 0.4
• Errors