Quickstart

Install

# programmatic SDK
npm install @ponraaj/dimple-sdk

# CLI (optional)
npm install -g @ponraaj/dimple

Runtime dependencies are the only things installed (Effect, libSQL, Transformers.js, drizzle) — the workspace internals are bundled into the package, including fully self-contained type declarations. The default install ships zero postinstall scripts: the local ONNX embedder is an optional peer, auto-installed on first use (autoInstall: false in the config opts out). Hosted embedding providers need nothing.

The one-liner

import { makeDimple } from "@ponraaj/dimple-sdk"; // ← makeDimple, not dimple

const dimple = await makeDimple({ config: "./dimple.jsonc" });
const hits = await dimple.query("what did we decide about X", {
  limit: 5,
  contentType: "text/plain", // ← code-vs-message separation
}); // query(text, options) — text is the FIRST positional argument
await dimple.dispose();

Calling conventions: every method takes plain arguments (query(text, opts), write(input, opts), index({ paths })), every failure is a rejected promise with a closed _tag ("Sdk.NotFound", "Sdk.InputError", …), and dispose() is required before process.exit(0) — the durable worker keeps the event loop alive.

Write + search

// write a memory (embeds + topic-routes it)
const mem = await dimple.write({
  logicalKey: "deploy-1",
  content: "the deploy pipeline runs on every push",
});

// hybrid semantic + FTS search
const results = await dimple.query("how does the pipeline deploy", {
  limit: 3,
});

write accepts namespace (default default), contentType (default text/plain), ttlSecs (default 7 days; null for code units), and metadata. Pass { embed: false } when embeddings are managed externally, then complete the memory with updateEmbedding(id, vector).

Index real code

// files + extracted functions/classes/methods become memories
const indexed = await dimple.index({ paths: ["./src"] });

Re-indexing is idempotent: unchanged units are skipped (and keep their git codeVersion stamp), changed units are superseded with a confirmed identity edge, deleted code is demoted (source_removed), and code_calls / import edges are rebuilt deterministically.

CLI equivalents

dimple init                # full annotated dimple.jsonc
dimple write "hello" --key k1
dimple query "hello" --limit 3 --json
dimple index ./src
dimple graph candidates    # pending edge review list
dimple db-schema           # table/column map