@ponraaj/dimple-sdk 0.0.0-alpha.1 → 0.0.0-alpha.10

package/README.md

@@ -0,0 +1,98 @@
+# @ponraaj/dimple-sdk
+
+A local-first memory system for AI agents: store text memories and whole
+codebases, retrieve them with hybrid semantic + lexical search, and let a
+self-organizing **topic tree + artifact graph + concepts** keep everything
+structured as it grows. Everything runs locally — ONNX embeddings on your
+CPU, SQLite files on disk.
+
+> **Documentation**: [dimple.ponraaj.me](https://dimple.ponraaj.me) —
+> quickstart, architecture, config reference, changelog ·
+> **Package**: [npmx.dev/package/@ponraaj/dimple](https://npmx.dev/package/@ponraaj/dimple) ·
+> **Status**: alpha (`0.0.0-alpha.n`) — the API is stabilizing.
+
+This is the programmatic SDK. The [`@ponraaj/dimple`](https://npmx.dev/package/@ponraaj/dimple)
+CLI is a thin facade over it.
+
+## Install
+
+```bash
+npm install @ponraaj/dimple-sdk
+```
+
+Runtime deps only (Effect, libSQL, transformers) — workspace internals are
+bundled, types are self-contained, and the default install ships **zero
+postinstall scripts** (the local ONNX embedder is an optional peer,
+auto-installed on first use).
+
+## Quickstart
+
+```ts
+import { makeDimple } from "@ponraaj/dimple-sdk"; // ← makeDimple, not dimple
+
+const dimple = await makeDimple({ config: "./dimple.jsonc" });
+
+// 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 hits = await dimple.query("how does the pipeline deploy", { limit: 3 });
+
+// index a codebase (tree-sitter: one unit per file + per definition)
+await dimple.index({ paths: ["./src"] });
+
+await dimple.dispose(); // required before process.exit — the durable worker
+```
+
+Calling conventions: **plain arguments** (`query(text, opts)`,
+`write(input, opts)`, `index({ paths })`); every failure is a rejected
+promise with a closed `_tag` (`"Sdk.NotFound"`, `"Sdk.InputError"`, …);
+`dispose()` is idempotent.
+
+## API surface
+
+| Method                                                    | What it does                                                                                                                                                            |
+| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `write(input, { embed })`                                 | Store a memory (idempotent per `logicalKey`)                                                                                                                            |
+| `writeMany(units, { embed })`                             | Bulk ingest: batch insert + batch embed + routing in one pass (skips the per-write candidate scan — quadratic under bulk; run the dream job afterwards for graph edges) |
+| `get(id)` / `forget(id)`                                  | Fetch / remove by id or logical key                                                                                                                                     |
+| `query(text, options)`                                    | Hybrid search — profiles, budgets, content-type filter                                                                                                                  |
+| `updateEmbedding(id, vec, modelKey?)`                     | Attach an external embedding                                                                                                                                            |
+| `index({ paths })`                                        | Codebase ingestion (idempotent re-index)                                                                                                                                |
+| `graph.addEdge/confirm/reject/expire/candidates/coverage` | Memory relationships: supports / supersedes / contradicts                                                                                                               |
+| `explain({ kind, id }, options)`                          | Bounded graph neighborhood                                                                                                                                              |
+| `dream(modelKey?)` / `repair(modelKey?)`                  | Consolidation + maintenance jobs                                                                                                                                        |
+| `health(modelKey?)`                                       | Topic-tree invariant health                                                                                                                                             |
+| `reload(input?)`                                          | Blue-green config reload                                                                                                                                                |
+
+Errors are a closed hierarchy (`InputError`, `NotFound`, `DuplicateKey`,
+`JobFailed`, `LLMNotConfigured`, `StoreFailure`) — see the docs site.
+
+## Configuration
+
+`makeDimple({ config: "./dimple.jsonc" })` — every section is optional
+except `embedding`. `dimple init` (CLI) writes the full annotated schema;
+`${ENV_VAR}` placeholders keep tokens out of files. The complete reference
+(store / jobs / embeddings / topics / graph / llm / logging / Turso) is on
+the docs site: [Configuration reference](https://dimple.ponraaj.me/reference/config/).
+
+## MCP server
+
+`dimple mcp` (from the CLI package) exposes dimple to any MCP client over
+the 2026-07-28 protocol — API discovery plus sandboxed code execution with
+the whole API as a `dimple` namespace. Guide:
+[MCP server & code mode](https://dimple.ponraaj.me/guides/mcp/).
+
+## Agent integration patterns
+
+Session-start injection, the supersedes recipe, and namespaces as the
+code/message partition are covered in the Architecture section of the
+docs site.
+
+## Changelog
+
+[Release history](https://dimple.ponraaj.me/changelog/sdk/) · repository
+[`CHANGELOG.md`](./CHANGELOG.md)

package/dist/dimple.d.ts

@@ -1,9 +1,11 @@
-import { ManagedRuntime } from "effect";
+import { Effect } from "effect";
 import type { QueryProfile } from "./internal/retriever/index.js";
 import type { CoreInterface } from "./internal/core/index.js";
 import type { CodeExtractor } from "./internal/extractor/index.js";
 import type { CodeParser } from "./internal/parser/index.js";
-import type { AddEdgeInput, AugmentedMemory, ExplainResult, GraphCandidatesResult, GraphCoverage, MemoryUnit, TopicHealth, WriteMemoryInput } from "./internal/store/index.js";
+import type { DimpleConfig } from "./internal/config/index.js";
+import type { AddEdgeInput, ArtifactEdge, AugmentedMemory, ExplainResult, GraphCandidatesResult, GraphCoverage, MemoryUnit, TopicHealth, WriteMemoryInput } from "./internal/store/index.js";
+import type { ConfigInput } from "./config.ts";
 import { type DimpleError } from "./errors.ts";
 /** Options for a `query` call — mirrors the hybrid retriever's options. */
 export interface QueryOptions {
@@ -16,6 +18,23 @@ export interface QueryOptions {
     readonly topics?: {
         readonly topicKeys?: ReadonlyArray<string>;
     };
+    /** Content-type filter: one kind or a list (e.g. `"text/x-typescript"`
+     * or `["text/plain", "text/markdown"]`) — the code-vs-message
+     * separation lever at query time. */
+    readonly contentType?: string | readonly string[];
+    /** Include the 384-float embedding on result memories (default false —
+     * search results never need vectors; the opt-in exists for callers that
+     * do post-processing with them). */
+    readonly includeEmbedding?: boolean;
+    /** Retrieval context budget (LLM-facing guardrail): `maxUnits` caps the
+     * row count, `maxChars` truncates result content to fit the total char
+     * budget, `maxMs` marks the result truncated when the query exceeds it.
+     * Truncation is surfaced as `results.truncated` on the returned array. */
+    readonly budget?: {
+        readonly maxUnits?: number;
+        readonly maxChars?: number;
+        readonly maxMs?: number;
+    };
 }
 /** Options for a `write` call. */
 export interface WriteOptions {
@@ -49,23 +68,65 @@ export interface IndexResult {
     readonly files: number;
     /** Memory units written (file unit + extracted chunks). */
     readonly indexed: number;
-    /** Units skipped as already-indexed (duplicate logical keys). */
+    /** Units whose active copy changed content — the old unit was
+     * superseded (confirmed `memory_supersedes` edge) and the new unit
+     * written under the same key. */
+    readonly updated: number;
+    /** Units whose source vanished from disk (deleted/moved file or
+     * definition) — demoted to superseded (`source_removed`); they no
+     * longer match queries. */
+    readonly reconciled: number;
+    /** The repo HEAD at index time (null outside a git tree) — stamped into
+     * every file/chunk unit's metadata as `codeVersion`. */
+    /** Units skipped as already-indexed (unchanged content under the same
+     * logical key). */
     readonly skipped: number;
     /** Files skipped because the extension is not indexable. */
     readonly unsupported: number;
+    readonly commit: string | null;
     /** Files that could not be walked/read/parsed/extracted/written. */
     readonly failed: readonly {
         readonly filePath: string;
         readonly message: string;
     }[];
 }
+/** What a `reload` actually changed — so callers can react (alert, log,
+ * refuse) instead of guessing. */
+export interface ReloadChanges {
+    /** The store database URL changed — the new db was bootstrapped (empty
+     * schema); the old db file is preserved on disk but no longer served.
+     * Nothing is migrated or merged. */
+    readonly storeUrl: boolean;
+    /** The jobs database URL changed — pending jobs stay durable in the
+     * old db (re-claimable by switching back or draining it externally). */
+    readonly jobsUrl: boolean;
+    /** Any other section changed (models, topics, graph, logging, …). */
+    readonly rest: boolean;
+}
+/** Result of a `reload`. */
+export interface ReloadResult {
+    readonly config: DimpleConfig;
+    readonly changed: ReloadChanges;
+    /** `false` when the resolved config was identical to the live one —
+     * nothing was paused, booted, or restarted (safe for watchers). */
+    readonly reloaded: boolean;
+}
 /**
  * The promise-based SDK facade — the ONLY surface app code touches.
  * Every method runs the underlying Effect at the boundary, remaps errors
  * onto the closed `DimpleError` hierarchy, and never leaks Effect types.
  */
 export interface Dimple {
+    /** The config-default embedding model's key — what `dream`/`repair`/
+     * `stats` use when no model is passed. */
+    readonly defaultModelId: string;
     readonly write: (input: WriteMemoryInput, options?: WriteOptions) => Promise<MemoryUnit>;
+    /** Bulk write: batch insert + batch embed + topic routing in ONE pass.
+     * Skips the per-write graph candidate scan (O(leaf size) per write —
+     * quadratic under bulk ingest); callers that need near-duplicate/
+     * conflict edges on bulk content should run the dream job afterwards.
+     * All-or-nothing: a duplicate logical key rejects the whole batch. */
+    readonly writeMany: (units: readonly WriteMemoryInput[], options?: WriteOptions) => Promise<readonly MemoryUnit[]>;
     readonly get: (id: string) => Promise<MemoryUnit>;
     readonly query: (text: string, options?: QueryOptions) => Promise<AugmentedMemory[]>;
     readonly forget: (id: string) => Promise<void>;
@@ -83,19 +144,66 @@ export interface Dimple {
     readonly embed: (text: string) => Promise<number[]>;
     readonly dream: (modelKey: string) => Promise<void>;
     readonly repair: (modelKey: string) => Promise<void>;
+    /** The store's tables + columns (snake_case DB names — the SDK exposes
+     * camelCase domain names; `dimple db-schema` prints this map). */
+    readonly dbSchema: () => Promise<ReadonlyArray<{
+        readonly table: string;
+        readonly columns: ReadonlyArray<{
+            readonly name: string;
+            readonly type: string;
+        }>;
+    }>>;
+    /** Options for `explain` — pass `edgeKinds` for a scoped answer (the
+     * common ask is memory-only navigation: the three `memory_*` kinds keep
+     * the topic/concept legs out). */
     readonly explain: (input: {
         readonly kind: "memory" | "topic" | "concept";
         readonly id: string;
+    }, options?: {
+        readonly edgeKinds?: readonly string[];
+        readonly maxDepth?: number;
+        readonly maxNeighbors?: number;
+        readonly maxTotal?: number;
+        readonly includePending?: boolean;
     }) => Promise<ExplainResult>;
     readonly health: (modelKey: string) => Promise<TopicHealth>;
     readonly graph: {
-        readonly addEdge: (input: AddEdgeInput) => Promise<unknown>;
+        readonly addEdge: (input: AddEdgeInput) => Promise<ArtifactEdge>;
         readonly candidates: () => Promise<GraphCandidatesResult>;
         readonly coverage: (modelKey: string) => Promise<GraphCoverage>;
+        /** Promote a pending edge to confirmed (for `memory_supersedes` the
+         * old endpoint flips to superseded in the same transaction). */
+        readonly confirm: (id: string) => Promise<void>;
+        /** Reject a pending edge (removed from the pending review set). */
+        readonly reject: (id: string) => Promise<void>;
+        /** Soft-delete an edge (`expired_at` set; excluded from traversal). */
+        readonly expire: (id: string) => Promise<void>;
     };
+    /**
+     * Apply a config change: pause (new calls wait, in-flight calls settle),
+     * boot a fresh stack with the re-resolved config, and swap it in.
+     *
+     * With no argument the ORIGINAL config source is re-resolved — a
+     * `dimple.jsonc` FILE PATH is re-read from disk, an inline object is
+     * re-validated. A config that fails validation or boot rejects the
+     * reload and leaves the current system untouched. An identical config
+     * resolves as `{ reloaded: false }` — no pause, no restart.
+     */
+    readonly reload: (input?: ConfigInput) => Promise<ReloadResult>;
     /** Stops the worker, closes the sinks and the store — idempotent. */
     readonly dispose: () => Promise<void>;
 }
+/**
+ * The live handles the facade reads at call time. `makeDimple` swaps the
+ * stack under this state on `reload`, so methods always hit the stack that
+ * is current when they run.
+ */
+export interface FacadeState {
+    readonly run: <A, E>(effect: Effect.Effect<A, E>) => Promise<A>;
+    readonly core: () => CoreInterface;
+    readonly parser: () => CodeParser["Service"];
+    readonly extractor: () => CodeExtractor["Service"];
+}
 /** Build the promise facade over the booted core + runtime. */
-export declare const makeFacade: <ER>(runtime: ManagedRuntime.ManagedRuntime<never, ER>, core: CoreInterface, parser: CodeParser["Service"], extractor: CodeExtractor["Service"], dispose: () => Promise<void>) => Dimple;
+export declare const makeFacade: (state: FacadeState, reload: (input?: ConfigInput) => Promise<ReloadResult>, dispose: () => Promise<void>) => Dimple;
 export type { DimpleError };

package/dist/errors.d.ts

@@ -45,19 +45,41 @@ declare const DuplicateEdgeError_base: Schema.Class<DuplicateEdgeError, Schema.T
 /** A duplicate memory↔memory edge (same from/to/kind already exists). */
 export declare class DuplicateEdgeError extends DuplicateEdgeError_base {
 }
+declare const EdgeNotFoundError_base: Schema.Class<EdgeNotFoundError, Schema.TaggedStruct<"Sdk.EdgeNotFound", {
+    readonly id: Schema.optional<Schema.String>;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** The edge does not exist (confirm/reject/expire on a stale id). */
+export declare class EdgeNotFoundError extends EdgeNotFoundError_base {
+}
 declare const StoreFailure_base: Schema.Class<StoreFailure, Schema.TaggedStruct<"Sdk.StoreFailure", {
     readonly message: Schema.String;
 }>, import("effect/Cause").YieldableError>;
 /** Anything else — the typed fallback that keeps the union closed. */
 export declare class StoreFailure extends StoreFailure_base {
 }
+declare const ReloadError_base: Schema.Class<ReloadError, Schema.TaggedStruct<"Sdk.Reload", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** `reload` was unavailable (no config source, disposed) or failed to
+ * drain in-flight calls before the swap. */
+export declare class ReloadError extends ReloadError_base {
+}
+declare const EmbeddingFailure_base: Schema.Class<EmbeddingFailure, Schema.TaggedStruct<"Sdk.Embedding", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** Embedding pipeline failure — the `@huggingface/transformers` package is
+ * missing (local embeddings), the model failed to load, or the output
+ * dimensions mismatch the config. */
+export declare class EmbeddingFailure extends EmbeddingFailure_base {
+}
 declare const InputError_base: Schema.Class<InputError, Schema.TaggedStruct<"Sdk.InputError", {
     readonly message: Schema.String;
 }>, import("effect/Cause").YieldableError>;
 /** Invalid SDK call input (bad `limit`, `k`, profile shape, …). */
 export declare class InputError extends InputError_base {
 }
-export type DimpleError = ConfigError | NotFoundError | DuplicateKeyError | DuplicateEdgeError | LLMNotConfiguredError | JobFailedError | StoreFailure | InputError;
+export type DimpleError = ConfigError | NotFoundError | DuplicateKeyError | DuplicateEdgeError | EdgeNotFoundError | LLMNotConfiguredError | EmbeddingFailure | JobFailedError | StoreFailure | ReloadError | InputError;
 /** Map an underlying failure onto the closed SDK hierarchy. */
-export declare const remapError: (error: unknown) => DimpleError;
+export declare const remapError: (cause: unknown) => DimpleError;
 export {};

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { makeDimple, type MakeDimpleOptions } from "./make.ts";
 export { type ConfigInput } from "./config.ts";
-export { type Dimple, type QueryOptions, type IndexOptions, type IndexResult } from "./dimple.ts";
-export { ConfigError, NotFoundError, DuplicateKeyError, DuplicateEdgeError, LLMNotConfiguredError, JobFailedError, StoreFailure, InputError, remapError, type DimpleError, } from "./errors.ts";
+export type { DimpleConfig } from "./internal/config/index.js";
+export { type Dimple, type QueryOptions, type IndexOptions, type IndexResult, type ReloadChanges, type ReloadResult, } from "./dimple.ts";
+export { ConfigError, NotFoundError, DuplicateKeyError, DuplicateEdgeError, EdgeNotFoundError, LLMNotConfiguredError, JobFailedError, StoreFailure, ReloadError, EmbeddingFailure, InputError, remapError, type DimpleError, } from "./errors.ts";