Configuration reference

The config loader is a strict JSONC parser (comments + trailing commas allowed). Every section is optional except embedding (without models there is nothing to embed or route). dimple init writes the full annotated schema. ${ENV_VAR} placeholders resolve from the environment — tokens never need to live in the config file. Validation reports ALL problems at once (not one error at a time).

{
  // ── store ────────────────────────────────────────────────────────────
  "storeUrl": "file:./.dimple/dimple.db",
  // remote (Turso): "libsql://<org>-<db>.turso.io?authToken=${TURSO_MEMORIES_TOKEN}"

  // ── durable jobs ─────────────────────────────────────────────────────
  "jobs": {
    "dbUrl": "file:./.dimple/jobs.db", // separate DB for the job queue
    "execution": "background", // background | inline | external
    "concurrency": 4,
    "leaseTimeoutMs": 120000,
    "maxAttempts": 10, // clamped to [1, 100]
    "pollIntervalMs": 1000,
  },

  // ── embeddings (REQUIRED) ────────────────────────────────────────────
  "embedding": {
    "defaultModel": "minilm", // the ACTIVE model for writes/queries
    "models": [
      // local — any Transformers.js ONNX model (auto-installed on first use)
      {
        "id": "minilm",
        "provider": "transformers",
        "model": "Xenova/all-MiniLM-L6-v2",
        "dimensions": 384,
        "autoInstall": true, // optional peer auto-install (default true)
        // per-model runtime options (all optional, defaults shown):
        // "device": "cpu",      // auto|gpu|cpu|wasm|webgpu|cuda|dml|coreml|webnn
        // "dtype": "q8",        // fp32|fp16|q8|int8|uint8|q4|bnb4|q4f16|q2|q2f16|q1|q1f16
        // "pooling": "mean",    // mean|cls|none
        // "normalize": true,
        // "cacheDir": "~/.cache/dimple",
        // "vectorType": "float32", // float32|float16|float8|float1bit
      },
      // hosted — any OpenAI-compatible endpoint (default https://api.openai.com/v1)
      {
        "id": "openai",
        "provider": "openai",
        "model": "text-embedding-3-small",
        "dimensions": 1536,
        "apiKey": "${OPENAI_API_KEY}",
        "baseURL": "https://api.openai.com/v1",
      },
      // native provider families — baseURL baked in, no baseURL needed
      // { "id": "gemini", "provider": "google", "model": "gemini-embedding-2", "dimensions": 3072, "apiKey": "…" }
      // { "id": "cohere", "provider": "cohere", "model": "embed-english-v3.0", "dimensions": 1024, "apiKey": "…" }
      // { "id": "titan",  "provider": "bedrock", "model": "amazon.titan-embed-text-v2:0", "dimensions": 1024 }
    ],
  },

  // ── topic tree shape (all optional — defaults shown) ─────────────────
  "topics": {
    "maxLeafItems": 128, // leaf overflow → split
    "minLeafItems": 32, // leaf underflow → borrow/merge
    "maxChildren": 16, // fan-out cap per split
    "minChildren": 4,
    "maxDepth": 6,
    "beamWidth": 3, // query descent beam
    "splitDeferredHardLimit": 512, // force-split backstop (4× maxLeafItems)
    "rebalanceCooldownMs": 60000, // min delay between rebalances
    "lloydPasses": 2, // k-means refinement passes
  },

  // ── artifact graph (all optional — defaults shown) ───────────────────
  "graph": {
    "enabled": true,
    "maxDepth": 2, // traversal depth
    "maxNeighbors": 12, // per-node fan-out
    "maxTotal": 80, // total neighborhood cap
    "supersedeDemotion": 0.5, // score penalty for superseded results
    "conflictBands": { "nearDuplicate": 0.9, "conflictLow": 0.6 },
    "clusterK": 8, // dream concept-clustering K
    "clusterMinSize": 3, // min members for a concept
  },

  // ── dream/repair LLM (optional — enables `dimple dream`) ─────────────
  "llm": {
    "baseURL": "https://api.openai.com/v1", // any OpenAI-compatible endpoint
    "apiKey": "${OPENAI_API_KEY}",
    "modelId": "gpt-4o-mini",
    "temperature": 0.2, // 0–2
    "maxOutputTokens": 512, // positive integer
    "reasoningEffort": "low", // low | medium | high
  },

  // ── logging (all optional — console is silent by default) ────────────
  "logging": {
    "enabled": true,
    "level": "info", // trace | debug | info | warn | error
    "format": "jsonl", // jsonl | pretty (console rendering)
    "file": "./.dimple/logs.jsonl", // durable JSONL sink (off unless set)
    "scopes": { "@dimple/store": "debug" }, // per-package level overrides
    "ringSize": 4096, // in-memory live tail
  },

  // ── retrieval/write defaults (all optional) ───────────────────────────
  "defaultK": 60, // RRF smoothing constant
  "defaultLimit": 10, // default result count
  "defaultTtlSecs": 604800, // default write TTL (7 days; null = never expires)
  "sweepIntervalMs": 300000, // expiry sweep cadence (5 minutes)
}

Remote databases (Turso)

storeUrl and jobs.dbUrl accept remote libSQL URLs (libsql://, https://, ws:// — Turso or any libsql-compatible host). The same engine runs everything the local file does — FTS5, vector search, the topic tree, durable jobs — over the wire (verified end-to-end against the real Turso service).

Turso tokens are per-database, so each URL carries its own token. ${ENV_VAR} resolution keeps them out of config files:

{
  "storeUrl": "libsql://<org>-<memdb>.turso.io?authToken=${TURSO_MEMORIES_TOKEN}",
  "jobs": { "dbUrl": "libsql://<org>-<memdb>.turso.io?authToken=${TURSO_MEMORIES_TOKEN}" },
}

Notes:

One DB serves both memories and the durable queue (separate table namespaces) — the simplest setup shares one URL + one token (TURSO_TOKEN works as the fallback). A dedicated jobs DB stays possible via TURSO_JOBS_URL / TURSO_JOBS_TOKEN
The jobs DB must also be remote when the store is remote (the durable queue + workflow state are cross-invocation)
file:-only behaviors (parent-dir creation, migration lock) skip for remote URLs
On edge runtimes, use hosted embedding providers (the local ONNX machinery is local/CLI-only)

Embedding models

Providers

`provider`	Models	`baseURL` needed?
`transformers`	any Transformers.js ONNX model — local, no keys (auto-installed on first use)	❌
`openai` (default)	any OpenAI-compatible endpoint — OpenAI, vLLM, ollama (`http://localhost:11434/v1`), Groq, Mistral, …	optional (defaults to OpenAI)
`google`	`gemini-embedding-001`, `gemini-embedding-2`, … (native provider)	❌ no
`cohere`	`embed-english-v3.0`, `embed-multilingual-v3.0`, … (native provider)	❌ no
`bedrock`	`amazon.titan-embed-text-v2:0`, `amazon.nova-embed-text-v2:0`, … (AWS creds from env)	❌ no

dimensions must match the model’s real output — a mismatch fails typed on first use. Multiple models coexist: each gets its own vector tables and its own topic tree; defaultModel picks the active one (queries route per model, backfill via the durable memory.embed job).

Transformers runtime options (per model, all optional)

Field	Values	Default	What it does
`device`	`auto` \| `gpu` \| `cpu` \| `wasm` \| `webgpu` \| `cuda` \| `dml` \| `coreml` \| `webnn`	`cpu`	execution backend (`cpu`/`wasm` tested; GPU needs the onnxruntime CUDA libs)
`dtype`	`fp32` \| `fp16` \| `q8` \| `int8` \| `uint8` \| `q4` \| `bnb4` \| `q4f16` \| `q2` \| `q2f16` \| `q1` \| `q1f16`	`q8`	quantizes the MODEL WEIGHTS (inference memory/speed) — never the output vectors
`pooling`	`mean` \| `cls` \| `none`	`mean`	sentence-pooling strategy
`normalize`	boolean	`true`	L2-normalize outputs
`cacheDir`	path	HF cache	override the model download cache
`autoInstall`	boolean	`true`	auto-install the optional `@huggingface/transformers` peer on first use (scripts skipped)

Vector storage quantization (`vectorType`)

The per-memory search vectors are stored in the model’s vec_<dims>_<model> table and searched with libSQL’s native vector_distance_cos:

`vectorType`	Encoding	384-dim stored	Tested
`float32` (default)	float32	1536 B	✅
`float16`	bfloat16	~790 B	seam exists
`float8`	int8	395 B (4×)	✅ write/query/health/split
`float1bit`	binary	~48 B (32×)	⚠️ l2 unsupported for 1bit

The topic tree’s centroid math and memories.embedding always stay float32 — quantization applies to the stored search vectors only.

Validation notes

All failures are typed with precise messages: temperature ∈ [0, 2]; maxAttempts and maxOutputTokens are positive integers (≤ 100 for maxAttempts); defaultModel must name a configured model (unknown keys fail at first use); dimensions mismatches fail on first embed; JSONC is strict (duplicate keys rejected); and multiple problems are reported in one pass.