Overview

Wolbarg 0.3 records what your agents' memory is doing into an independent telemetry database — never the same tables as your memory store. You then explore it with Wolbarg Studio, a local dashboard that opens that database read-only.

Enabling telemetry

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",
  }),
  telemetry: {
    enabled: true,
    database: { provider: "sqlite", url: "./telemetry.db" },
    level: "debug", // off | error | warn | info | debug | trace
    captureQueries: true,
    captureLatency: true,
    captureErrors: true,
    captureSimilarity: true,
  },
});

Every operation (remember, recall, ingest, compress, checkpoint, rollback, rememberBatch, recallBatch, …) emits an event with:

session_id, trace_id, parent_trace_id — for waterfall traces
organization, agent, tags, checkpoint_id
measured stage spans (embedding, vector search, ranking, database read/write)
persisted recall explanations when explain: true

Call await ctx.flushTelemetry() before exiting short-lived scripts to ensure the async emitter drains.

Telemetry is SQLite-only in v0.3 (the interface is ready for Postgres). It is fully independent of your memory backend, so you can use Postgres for memory and SQLite for telemetry.

Recall explain mode

const explained = await ctx.recall({ query: "recurring invoices", explain: true });

for (const hit of explained.results) {
  console.log(hit.memory.id, hit.score, hit.rankingReason);
}
console.log(explained.searchTime, explained.rankingTime, explained.traceId);

Schema versioning

Telemetry SQLite files use an additive, versioned schema. On writable open, v1 files are migrated in place to v2 and keep all existing events. V2 adds organization, agent, tags, checkpoint, persisted recall explanations, and stage spans. Read-only access to an unmigrated v1 file remains supported.

SqliteEventDatabase.query() can filter by organization, agentId, tag, and checkpointId.

Wolbarg Studio

Studio is a standalone dashboard (Next.js) — not bundled into the SDK. The SDK writes events; Studio reads them.

git clone https://github.com/Atharvmunde11/wolbarg-studio
cd wolbarg-studio
npm install
npm run dev   # http://localhost:3100

On first launch, connect a telemetry database path (e.g. ./telemetry.db). Connections persist in your user config directory (~/.wolbarg/studio.json or the AppData equivalent), never inside the project.

What Studio shows

Dashboard — live stat cards (operations today, error rate, throughput, P95 latency, active agents, memory/telemetry counts) plus operation distribution, ops-per-minute, latency-over-time, error, and checkpoint-activity charts, and a top-slow-recalls list
Events — filterable operation stream with a detail view
Traces — waterfall timeline for a trace_id and its child spans
Recalls — recall queries with scores, timings, and explanations
Operations — per-operation breakdowns and latencies
Errors — failed operations grouped for triage
Agents — per-agent activity, with a drill-down detail page
Checkpoints — snapshot activity captured from telemetry
Stream — live event tailing
Settings — connection, refresh interval, and theme

Notes

Studio opens SQLite read-only — it never writes to your telemetry or memory databases
Live mode polls on a configurable interval (default 2s)
Postgres telemetry connections are represented in config but not implemented yet

Observability & Studio