Skip to content
Memoturn

Getting started

Prerequisites

Section titled “Prerequisites”
  • Bun ≥ 1.3 (package manager + runtime)
  • Docker (Postgres, Apache Doris, Redis/Valkey, MinIO) — give Docker ~4 GB of memory; the Doris FE + BE want it. Don’t want to run Doris? Set TELEMETRY_ENGINE=postgres in .env for the lightweight Postgres telemetry tier — every step below stays the same, minus the Doris containers.
  • uv — only if you work on the Python SDK

Install & run

Section titled “Install & run”
Terminal window
git clone git@github.com:memoturn/memoturn.git
cd memoturn
cp .env.example .env
bun run setup     # install + start infra + wait healthy + migrate + telemetry DDL + seed
bun run dev       # api (:3001) + worker + console (:3000)

bun run setup runs, in order:

  1. bun install (also regenerates the Prisma client + installs git hooks)
  2. bun run infra:up — start the dependency containers
  3. bun run infra:wait — block until Postgres/Redis/Doris/MinIO are reachable
  4. bun run db:migrate — apply Prisma (Postgres) migrations
  5. bun run db:telemetry — apply the Doris DDL (infra/doris/*.sql; each file applies at most once)
  6. bun run seed — create a default workspace/project, a dev API key, a login user, and a sample prompt

What you get

Section titled “What you get”
SurfaceURL / value
Console (dashboard)http://localhost:3000
Dashboard loginadmin@memoturn.dev / memoturn-dev-123
APIhttp://localhost:3001
API reference (Scalar)http://localhost:3001/docs
OpenAPI documenthttp://localhost:3001/openapi.json
Dev API key (SDKs)pk-mt-dev / sk-mt-dev

The memoturn dashboard — traces, generations, tokens, and cost over the last 30 days

Emit your first trace

Section titled “Emit your first trace”
Terminal window
bun run quickstart        # TypeScript SDK → a trace with a span + generation + score

Open http://localhost:3000/traces and click the trace to see the waterfall timeline and its scores.

Trace detail — observations on a waterfall timeline, with scores and payloads

Fill the dashboards with demo data

Section titled “Fill the dashboards with demo data”

One trace makes for an empty dashboard. To exercise the metrics, trace list, and sessions views with realistic volume, seed ~30 days of backdated demo telemetry (requires bun run dev running — data flows through the real ingest pipeline):

Terminal window
bun run seed:demo                                  # 30 days × ~1000 traces/day
bun run seed:demo -- --days 7 --traces-per-day 100 # smaller/faster
bun run seed:demo -- --dry-run                     # generate + validate only, send nothing
bun run seed:demo -- --wipe                        # wipe the project's telemetry first

The run is deterministic (--seed): re-running on the same day replaces the same rows instead of duplicating them. On a later day the seeded window shifts forward, so pass --wipe to start clean — note that it deletes all of the project’s telemetry (not just previously seeded rows) before seeding.

Common commands

Section titled “Common commands”
Terminal window
bun run dev          # run api + worker + console (turbo)
bun run lint         # Biome (format + lint + import order)
bun run format       # auto-fix
bun run typecheck
bun run test
bun run build
bun run infra:down   # stop the dependency containers

Next: Architecture · Data model