@theokit/sdk-memory 0.3.1 → 0.3.3

package/dist/internal/embedding/mistral-embedding.d.ts

@@ -12,5 +12,13 @@ import type { MemoryEmbeddingProviderAdapter } from "./embedding-adapter.js";
  * @internal
  */
 export declare const DEFAULT_MISTRAL_EMBEDDING_MODEL = "mistral-embed";
+/**
+ * Mistral embeddings, over the standard OpenAI wire. One model only,
+ * `mistral-embed` at 1024 dimensions; any other id is refused with
+ * `embedding_unknown_model`.
+ *
+ * Reads `MISTRAL_API_KEY` and honours `MISTRAL_API_BASE_URL`. Priority 18, just
+ * below OpenAI.
+ */
 export declare const mistralMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;
 //# sourceMappingURL=mistral-embedding.d.ts.map

package/dist/internal/embedding/mistral-embedding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mistral-embedding.d.ts","sourceRoot":"","sources":["../../../src/internal/embedding/mistral-embedding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,wBAAwB,CAAC;AAK7E;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,+BAA+B,kBAAkB,CAAC;AAM/D,eAAO,MAAM,qCAAqC,EAAE,8BAkBnD,CAAC"}
+{"version":3,"file":"mistral-embedding.d.ts","sourceRoot":"","sources":["../../../src/internal/embedding/mistral-embedding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,wBAAwB,CAAC;AAK7E;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,+BAA+B,kBAAkB,CAAC;AAM/D;;;;;;;GAOG;AACH,eAAO,MAAM,qCAAqC,EAAE,8BAkBnD,CAAC"}

package/dist/internal/embedding/ollama-embedding.d.ts

@@ -36,6 +36,27 @@
  * @internal
  */
 import type { MemoryEmbeddingProviderAdapter } from "./embedding-adapter.js";
+/**
+ * Model used when the caller names none: `nomic-embed-text`, 768 dimensions,
+ * roughly 274MB to pull. `all-minilm` is the smaller alternative at 384
+ * dimensions and roughly 45MB.
+ */
 export declare const DEFAULT_OLLAMA_EMBEDDING_MODEL = "nomic-embed-text";
+/**
+ * Embeddings from a local Ollama instance — the only adapter in the catalog with
+ * `transport: "local"`, and the one to choose when the corpus must not leave the
+ * machine or when there is no API key to spend.
+ *
+ * It needs an Ollama server reachable at `OLLAMA_HOST` (default
+ * `http://localhost:11434`) with the chosen embedding model already pulled;
+ * nothing here starts a server or downloads a model, so a missing model surfaces
+ * as an HTTP error from Ollama rather than a configuration error.
+ *
+ * No credential is required: a sentinel key is sent and local Ollama ignores it.
+ * Set `OLLAMA_API_KEY` for Ollama Cloud or an authenticating reverse proxy.
+ *
+ * Auto-select priority is 10, the lowest in the catalog, so a configured remote
+ * provider wins over it. Request it explicitly to prefer local.
+ */
 export declare const ollamaMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;
 //# sourceMappingURL=ollama-embedding.d.ts.map

package/dist/internal/embedding/ollama-embedding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ollama-embedding.d.ts","sourceRoot":"","sources":["../../../src/internal/embedding/ollama-embedding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,wBAAwB,CAAC;AAK7E,eAAO,MAAM,8BAA8B,qBAAqB,CAAC;AAsBjE,eAAO,MAAM,oCAAoC,EAAE,8BAyBlD,CAAC"}
+{"version":3,"file":"ollama-embedding.d.ts","sourceRoot":"","sources":["../../../src/internal/embedding/ollama-embedding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,wBAAwB,CAAC;AAK7E;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,qBAAqB,CAAC;AAsBjE;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,oCAAoC,EAAE,8BAyBlD,CAAC"}

package/dist/internal/embedding/openai-embedding.d.ts

@@ -1,16 +1,4 @@
 import type { MemoryEmbeddingProviderAdapter } from "./embedding-adapter.js";
-/**
- * **Iter 74 rollup-plugin-dts workaround:** importing
- * `MemoryEmbeddingProviderAdapter` from sibling `./embedding-adapter.js`
- * fails dts emit because no public type reaches it transitively yet
- * (same iter 48/53/55/66/67/69/72 class). Fix: drop the explicit
- * type annotation on the exported adapter; TS infers the structural
- * shape from the literal, and the catalog (iter 37 / this same iter)
- * pin assignability against the canonical interface via its own
- * `Record<string, MemoryEmbeddingProviderAdapter>` constraint.
- *
- * @internal
- */
 /**
  * OpenAI embedding adapter (ADR D3) — built on the shared OpenAI-compatible
  * factory. Native fetch only.
@@ -23,5 +11,24 @@ import type { MemoryEmbeddingProviderAdapter } from "./embedding-adapter.js";
  * @internal
  */
 export declare const DEFAULT_OPENAI_EMBEDDING_MODEL = "text-embedding-3-small";
+/**
+ * OpenAI embeddings — `text-embedding-3-small` (1536), `text-embedding-3-large` (3072) and
+ * `text-embedding-ada-002` (1536).
+ *
+ * It is NOT selected for you. The provider is whatever the caller names in
+ * `embedding: { provider }`; omit that and no embedding runtime is built at all. Its
+ * `autoSelectPriority` of `20` is metadata no code path reads today, and it is not the highest
+ * value in the catalog either — `jina` is 35, `cohere` and `gemini` are 30, `azure-openai` is 25.
+ * The 3072-wide `text-embedding-3-large` is reachable through `azure-openai` and, as
+ * `openai/text-embedding-3-large`, through `openrouter` as well.
+ *
+ * Reads `OPENAI_API_KEY`; `OPENAI_API_BASE_URL` redirects it at a compatible
+ * gateway. `create` rejects with an `AuthenticationError`
+ * (`embedding_missing_api_key`) when no key is found, and with a
+ * `ConfigurationError` (`embedding_unknown_model`) for a model outside
+ * `text-embedding-3-small`, `text-embedding-3-large` and
+ * `text-embedding-ada-002` — the dimension has to be known before any vector
+ * table is created, so an unlisted model is refused rather than probed.
+ */
 export declare const openAiMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;
 //# sourceMappingURL=openai-embedding.d.ts.map

package/dist/internal/embedding/openai-embedding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openai-embedding.d.ts","sourceRoot":"","sources":["../../../src/internal/embedding/openai-embedding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,wBAAwB,CAAC;AAG7E;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,8BAA8B,2BAA2B,CAAC;AAQvE,eAAO,MAAM,oCAAoC,EAAE,8BAkBlD,CAAC"}
+{"version":3,"file":"openai-embedding.d.ts","sourceRoot":"","sources":["../../../src/internal/embedding/openai-embedding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,wBAAwB,CAAC;AAY7E;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,8BAA8B,2BAA2B,CAAC;AAQvE;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,oCAAoC,EAAE,8BAkBlD,CAAC"}

package/dist/internal/embedding/openrouter-embedding.d.ts

@@ -14,5 +14,17 @@ import type { MemoryEmbeddingProviderAdapter } from "./embedding-adapter.js";
  * @internal
  */
 export declare const DEFAULT_OPENROUTER_EMBEDDING_MODEL = "openai/text-embedding-3-small";
+/**
+ * Embeddings routed through OpenRouter, which lets one key reach several
+ * upstream providers. Use it when you want to switch provider without changing
+ * credentials; use the provider's own adapter when you want its full model
+ * range, since only the four ids in this adapter's dimension table are
+ * accepted.
+ *
+ * Model ids carry the upstream prefix, for example
+ * `openai/text-embedding-3-small` or `mistralai/mistral-embed`. The endpoint is
+ * `/v1/embeddings` under the base `https://openrouter.ai/api`. Reads
+ * `OPENROUTER_API_KEY` and honours `OPENROUTER_API_BASE_URL`. Priority 15.
+ */
 export declare const openRouterMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;
 //# sourceMappingURL=openrouter-embedding.d.ts.map

package/dist/internal/embedding/openrouter-embedding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openrouter-embedding.d.ts","sourceRoot":"","sources":["../../../src/internal/embedding/openrouter-embedding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,wBAAwB,CAAC;AAK7E;;;;;;;;;;;;;GAaG;AAEH,eAAO,MAAM,kCAAkC,kCAAkC,CAAC;AASlF,eAAO,MAAM,wCAAwC,EAAE,8BAkBtD,CAAC"}
+{"version":3,"file":"openrouter-embedding.d.ts","sourceRoot":"","sources":["../../../src/internal/embedding/openrouter-embedding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,wBAAwB,CAAC;AAK7E;;;;;;;;;;;;;GAaG;AAEH,eAAO,MAAM,kCAAkC,kCAAkC,CAAC;AASlF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wCAAwC,EAAE,8BAkBtD,CAAC"}

package/dist/internal/embedding/voyage-embedding.d.ts

@@ -12,5 +12,14 @@ import type { MemoryEmbeddingProviderAdapter } from "./embedding-adapter.js";
  * @internal
  */
 export declare const DEFAULT_VOYAGE_EMBEDDING_MODEL = "voyage-3-lite";
+/**
+ * Voyage AI embeddings, over the standard OpenAI wire. Default model
+ * `voyage-3-lite` at 512 dimensions — the narrowest in the catalog, which makes
+ * the index smaller and the search cheaper at some cost in quality; `voyage-3`
+ * and `voyage-3-large` are 1024, and `voyage-code-3` is the one to pick for
+ * source code.
+ *
+ * Reads `VOYAGE_API_KEY` and honours `VOYAGE_API_BASE_URL`. Priority 14.
+ */
 export declare const voyageMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;
 //# sourceMappingURL=voyage-embedding.d.ts.map

package/dist/internal/embedding/voyage-embedding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"voyage-embedding.d.ts","sourceRoot":"","sources":["../../../src/internal/embedding/voyage-embedding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,wBAAwB,CAAC;AAK7E;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,8BAA8B,kBAAkB,CAAC;AAU9D,eAAO,MAAM,oCAAoC,EAAE,8BAkBlD,CAAC"}
+{"version":3,"file":"voyage-embedding.d.ts","sourceRoot":"","sources":["../../../src/internal/embedding/voyage-embedding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,wBAAwB,CAAC;AAK7E;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,8BAA8B,kBAAkB,CAAC;AAU9D;;;;;;;;GAQG;AACH,eAAO,MAAM,oCAAoC,EAAE,8BAkBlD,CAAC"}

package/dist/internal/index/index-db.d.ts

@@ -37,6 +37,7 @@ export interface MemoryDb {
     /** Load a SQLite loadable extension at the given path (used by sqlite-vec). */
     loadExtension(path: string): void;
 }
+/** Options for {@link openMemoryDb}. */
 export interface OpenDbOptions {
     filePath: string;
     /**
@@ -45,6 +46,30 @@ export interface OpenDbOptions {
      */
     recoverCorrupt?: boolean;
 }
+/**
+ * Open (or create) the SQLite memory index at `filePath`, applying the pragmas
+ * and creating the schema before returning. Parent directories are created as
+ * needed, so pointing this at a fresh workspace works.
+ *
+ * The driver is chosen at runtime: `node:sqlite` where the running Node exposes
+ * it, and `better-sqlite3` otherwise. `better-sqlite3` is an optional peer
+ * dependency of this package — on a Node build without `node:sqlite` and
+ * without it installed, opening fails.
+ *
+ * A file that is corrupt, truncated or encrypted is renamed aside to
+ * `<path>.corrupt-<timestamp>` and rebuilt empty, unless `recoverCorrupt` is
+ * `false`. Recovery loses every indexed chunk; the markdown corpus is the source
+ * of truth and the next `sync()` rebuilds from it.
+ *
+ * Loading the sqlite-vec extension is a separate step — this returns an index
+ * that can do text search only.
+ */
 export declare function openMemoryDb(opts: OpenDbOptions): Promise<MemoryDb>;
+/**
+ * Where the SQLite index lives when the caller does not name a path:
+ * `<cwd>/.theokit/memory/.index/memory.sqlite`. Pure path computation. The file
+ * sits under the memory root but outside the markdown corpus, so it is never
+ * indexed as content.
+ */
 export declare function defaultIndexPath(cwd: string): string;
 //# sourceMappingURL=index-db.d.ts.map

package/dist/internal/index/index-db.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index-db.d.ts","sourceRoot":"","sources":["../../../src/internal/index/index-db.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG;QACpB,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAAA;SAAE,CAAC;QAC/E,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;QAC7D,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;KACzD,CAAC;IACF,iEAAiE;IACjE,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC;IACnE,KAAK,IAAI,IAAI,CAAC;IACd,+EAA+E;IAC/E,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,QAAQ,CAAC,CAWzE;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEpD"}
+{"version":3,"file":"index-db.d.ts","sourceRoot":"","sources":["../../../src/internal/index/index-db.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG;QACpB,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAAA;SAAE,CAAC;QAC/E,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;QAC7D,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;KACzD,CAAC;IACF,iEAAiE;IACjE,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC;IACnE,KAAK,IAAI,IAAI,CAAC;IACd,+EAA+E;IAC/E,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED,wCAAwC;AACxC,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,QAAQ,CAAC,CAWzE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEpD"}

package/dist/internal/index/index-manager-contract.d.ts

@@ -42,12 +42,31 @@ export interface MemorySearchHit {
     /** path:startLine-endLine for citations. */
     citation: string;
 }
+/**
+ * A snapshot of index health. `backend` is `hybrid` when a vector index is live
+ * and `fts-only` when the index can do text search only, which is what an index
+ * opened without an embedding runtime reports.
+ *
+ * `lastSyncMs` is present only after a `sync()` in this process; it is not
+ * persisted, so a freshly opened index omits it however recently it was synced.
+ */
 export interface IndexStatus {
     backend: "fts-only" | "hybrid";
     filesIndexed: number;
     chunksIndexed: number;
     lastSyncMs?: number;
 }
+/**
+ * Search tuning. `maxResults` defaults to 10 and is floored at 1. `minScore`
+ * defaults to 0 and is compared against the combined score, not the text or
+ * vector score alone. `sources` filters by corpus; omitting it searches all
+ * three.
+ *
+ * The two weights only matter on a hybrid index — with no vector index every
+ * vector score is 0, so raising `vectorWeight` only scales the text score down.
+ * They are normalised by their sum, so `{vectorWeight: 6, textWeight: 4}`
+ * behaves the same as the defaults.
+ */
 export interface SearchOptions {
     maxResults?: number;
     minScore?: number;
@@ -59,6 +78,15 @@ export interface SearchOptions {
 }
 /** Vector backend selector. SQLite default; Lance opt-in (ADR D43). */
 export type MemoryBackend = "sqlite-vec" | "lance";
+/**
+ * Options for `IndexManager.open`.
+ *
+ * Passing `embedding` is what turns on vector search; without it the index is
+ * text-only. The Lance backend requires it and refuses to open without one.
+ *
+ * `filePath` means different things per backend: on `sqlite-vec` it is the
+ * database file, on `lance` it is the storage directory.
+ */
 export interface OpenIndexOptions {
     cwd: string;
     filePath?: string;

package/dist/internal/index/index-manager-contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index-manager-contract.d.ts","sourceRoot":"","sources":["../../../src/internal/index/index-manager-contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,MAAM,WAAW,eAAe;IAC9B,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,KAAK,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,sGAAsG;IACtG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC;IACvC,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,UAAU,GAAG,QAAQ,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,aAAa,CAAC,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC,CAAC;IACxD,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,uEAAuE;AACvE,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG,OAAO,CAAC;AAEnD,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,oEAAoE;IACpE,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB"}
+{"version":3,"file":"index-manager-contract.d.ts","sourceRoot":"","sources":["../../../src/internal/index/index-manager-contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,MAAM,WAAW,eAAe;IAC9B,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,KAAK,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,sGAAsG;IACtG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC;IACvC,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,UAAU,GAAG,QAAQ,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,aAAa,CAAC,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC,CAAC;IACxD,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,uEAAuE;AACvE,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG,OAAO,CAAC;AAEnD;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,oEAAoE;IACpE,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB"}

package/dist/internal/index/index-manager.d.ts

@@ -49,6 +49,35 @@ interface OpenIndexOptions {
     embedding?: EmbeddingRuntime;
     backend?: "sqlite-vec" | "lance";
 }
+/**
+ * The default memory index: SQLite for storage, FTS5 for text matching, and
+ * sqlite-vec for vectors when an embedding runtime is supplied.
+ *
+ * Open it with the static `open`, which is also the dispatch point for
+ * `backend: "lance"` — that overload returns a `LanceMemoryAdapter`, not an
+ * `IndexManager`, so hold the result as {@link MemoryIndex} unless you need this
+ * class specifically.
+ *
+ * Storage needs `better-sqlite3` unless the running Node exposes `node:sqlite`,
+ * and vectors additionally need `sqlite-vec`. Both are optional peer
+ * dependencies of this package. Without an embedding runtime the index opens
+ * text-only and reports `backend: "fts-only"`; no vector table is created and
+ * search degrades to BM25 rather than failing.
+ *
+ * `sync()` crawls the markdown corpus — `MEMORY.md`, `notes/`, `wiki/` and
+ * `sessions/` — skipping files whose content hash has not moved, and re-chunking
+ * the rest. Nothing is indexed until it runs.
+ *
+ * If the embedding provider, model or dimension differs from what the database
+ * recorded, opening drops the whole vector table so the next `sync()` re-embeds
+ * from scratch. Switching embedding models is therefore safe but not cheap.
+ *
+ * `search()` runs both halves and blends them per chunk, so a chunk found only
+ * by vector still appears with a text score of 0 and the other way round.
+ * `close()` releases the database handle; it is synchronous here, unlike the
+ * Lance adapter's, so a caller holding the {@link MemoryIndex} type must await
+ * it either way.
+ */
 export declare class IndexManager implements MemoryIndex {
     private readonly cwd;
     private readonly db;

package/dist/internal/index/index-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index-manager.d.ts","sourceRoot":"","sources":["../../../src/internal/index/index-manager.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAO1E,OAAO,EAAE,KAAK,WAAW,EAAsB,MAAM,mBAAmB,CAAC;AAYzE;;;;;;;;;;;;;;;;;;GAkBG;AAmBH,UAAU,eAAe;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC;IAChD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,UAAU,WAAW;IACnB,OAAO,EAAE,UAAU,GAAG,QAAQ,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,UAAU,aAAa;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,aAAa,CAAC,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC,CAAC;CACzD;AAED,UAAU,gBAAgB;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC;CAClC;AAED,qBAAa,YAAa,YAAW,WAAW;IAK5C,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAN5B,OAAO,CAAC,UAAU,CAAqB;IACvC,OAAO,CAAC,WAAW,CAAS;IAE5B,OAAO;IAMP;;;;OAIG;WACU,IAAI,CAAC,IAAI,EAAE,gBAAgB,GAAG;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,CAAC;WACzE,IAAI,CACf,IAAI,EAAE,IAAI,CAAC,gBAAgB,EAAE,SAAS,CAAC,GAAG,CAAC,gBAAgB,GAAG;QAAE,OAAO,CAAC,EAAE,YAAY,CAAA;KAAE,CAAC,GACxF,OAAO,CAAC,YAAY,CAAC;IAQxB,sEAAsE;mBACjD,kBAAkB;YAQzB,iBAAiB;IAkB/B,wDAAwD;IAClD,IAAI,IAAI,OAAO,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,CAAC;QACtB,cAAc,EAAE,MAAM,CAAC;KACxB,CAAC;IAkCI,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAYpF,MAAM,IAAI,WAAW;IAcrB,OAAO,CAAC,SAAS;YA4CH,gBAAgB;IAiB9B,OAAO,CAAC,mBAAmB;IAa3B,OAAO,CAAC,SAAS;IAejB,OAAO,CAAC,gBAAgB;IAkCxB,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,UAAU;IAgBlB,OAAO,CAAC,mBAAmB;IAI3B,OAAO,CAAC,WAAW;IAcnB,KAAK,IAAI,IAAI;CAGd"}
+{"version":3,"file":"index-manager.d.ts","sourceRoot":"","sources":["../../../src/internal/index/index-manager.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAO1E,OAAO,EAAE,KAAK,WAAW,EAAsB,MAAM,mBAAmB,CAAC;AAYzE;;;;;;;;;;;;;;;;;;GAkBG;AAmBH,UAAU,eAAe;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC;IAChD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,UAAU,WAAW;IACnB,OAAO,EAAE,UAAU,GAAG,QAAQ,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,UAAU,aAAa;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,aAAa,CAAC,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC,CAAC;CACzD;AAED,UAAU,gBAAgB;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,YAAa,YAAW,WAAW;IAK5C,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAN5B,OAAO,CAAC,UAAU,CAAqB;IACvC,OAAO,CAAC,WAAW,CAAS;IAE5B,OAAO;IAMP;;;;OAIG;WACU,IAAI,CAAC,IAAI,EAAE,gBAAgB,GAAG;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,CAAC;WACzE,IAAI,CACf,IAAI,EAAE,IAAI,CAAC,gBAAgB,EAAE,SAAS,CAAC,GAAG,CAAC,gBAAgB,GAAG;QAAE,OAAO,CAAC,EAAE,YAAY,CAAA;KAAE,CAAC,GACxF,OAAO,CAAC,YAAY,CAAC;IAQxB,sEAAsE;mBACjD,kBAAkB;YAQzB,iBAAiB;IAkB/B,wDAAwD;IAClD,IAAI,IAAI,OAAO,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,CAAC;QACtB,cAAc,EAAE,MAAM,CAAC;KACxB,CAAC;IAkCI,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAYpF,MAAM,IAAI,WAAW;IAcrB,OAAO,CAAC,SAAS;YA4CH,gBAAgB;IAiB9B,OAAO,CAAC,mBAAmB;IAa3B,OAAO,CAAC,SAAS;IAejB,OAAO,CAAC,gBAAgB;IAkCxB,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,UAAU;IAgBlB,OAAO,CAAC,mBAAmB;IAI3B,OAAO,CAAC,WAAW;IAcnB,KAAK,IAAI,IAAI;CAGd"}

package/dist/internal/index/lance-index.d.ts

@@ -1,4 +1,13 @@
 import type { EmbeddingRuntime } from "../embedding/embedding-adapter.js";
+/**
+ * One row of the Lance `facts` table, as it is stored. Field names are the
+ * on-disk column names, which is why `user_id` is snake_case here while the
+ * search result reports `userId`.
+ *
+ * `embedding` must be exactly as wide as the table was created with; the width
+ * is fixed by the embedding runtime on the first open and checked on every
+ * later one.
+ */
 export interface LanceFactRecord {
     id: string;
     text: string;
@@ -9,18 +18,34 @@ export interface LanceFactRecord {
     user_id: string;
     timestamp: number;
 }
+/**
+ * Options for `LanceIndex.open`. The embedding runtime is required, not
+ * optional: Lance here is vector-only, so there is no text-search fallback to
+ * open without one.
+ */
 export interface OpenLanceOptions {
     cwd: string;
     embedding: EmbeddingRuntime;
     /** Override storage location. Default: `<cwd>/.theokit/memory/lance/`. */
     storagePath?: string;
 }
+/**
+ * Filters for `LanceIndex.search`. `namespace` is required and `scope` is
+ * optional; both are applied as a SQL predicate inside Lance. `sources` is
+ * applied in this process, after the rows come back, so it narrows the result
+ * without narrowing what `limit` counted.
+ */
 export interface LanceSearchOptions {
     namespace: string;
     scope?: string;
     limit?: number;
     sources?: ReadonlyArray<"memory" | "sessions" | "wiki">;
 }
+/**
+ * One Lance search result. `score` is a similarity in `(0, 1]` derived from
+ * Lance's distance as `1 / (1 + distance)`, so higher is better — the opposite
+ * direction from the raw distance Lance returns.
+ */
 export interface LanceSearchHit {
     id: string;
     text: string;

package/dist/internal/index/lance-index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lance-index.d.ts","sourceRoot":"","sources":["../../../src/internal/index/lance-index.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AA+D1E,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC;IACvC,SAAS,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,gBAAgB,CAAC;IAC5B,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,aAAa,CAAC,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC,CAAC;CACzD;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAoBD;;;;;GAKG;AACH,qBAAa,UAAU;IAEnB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAH/B,OAAO;WAMM,IAAI,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IA2CxD,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,eAAe,EAAE,WAAW,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAWvF;;;;OAIG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IA+B1E,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAQ9C,WAAW,CAAC,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAUtD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B;AAiCD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAQ1C;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEpD"}
+{"version":3,"file":"lance-index.d.ts","sourceRoot":"","sources":["../../../src/internal/index/lance-index.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AA+D1E;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC;IACvC,SAAS,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,gBAAgB,CAAC;IAC5B,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,aAAa,CAAC,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC,CAAC;CACzD;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAoBD;;;;;GAKG;AACH,qBAAa,UAAU;IAEnB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAH/B,OAAO;WAMM,IAAI,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IA2CxD,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,eAAe,EAAE,WAAW,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAWvF;;;;OAIG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IA+B1E,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAQ9C,WAAW,CAAC,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAUtD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B;AAiCD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAQ1C;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEpD"}

package/dist/internal/index/lance-memory-adapter.d.ts

@@ -11,11 +11,13 @@
  *    facts use `LanceIndex.addFacts` directly (exposed via the index
  *    object returned to advanced callers).
  *  - `search()` performs vector-only retrieval. `MemorySearchHit.textScore`
- *    is undefined (no FTS5 layer); `vectorScore === score`.
- *  - `status()` reports `backend: "hybrid"` only when an embedding runtime
- *    is wired (always the case for Lance — embedding is required at open).
- *    `chunksIndexed` reflects total Lance row count; `filesIndexed` is 0
- *    because Lance does not track file provenance per-row.
+ *    is 0 on every hit (no FTS5 layer); `vectorScore === score`.
+ *  - `status()` always reports `backend: "hybrid"` — embedding is required
+ *    at open, so there is no text-only Lance index. Both counts are 0: the
+ *    Lance row count is only available asynchronously and `status()` is
+ *    synchronous, so callers needing a real count call
+ *    `unwrap().countFacts()`. Lance does not track file provenance per row,
+ *    so `filesIndexed` has nothing to report either way.
  *
  * Ships with the lancedb-backend-ship-v1-1 plan (close D12, supersede via
  * D43). v1.4.0 of `@theokit/sdk`.
@@ -81,6 +83,26 @@ interface LanceIndex {
     removeFacts(ids: ReadonlyArray<string>): Promise<void>;
     close(): Promise<void>;
 }
+/**
+ * Presents a `LanceIndex` as a {@link MemoryIndex}, so a consumer written
+ * against the SQLite index runs unchanged on `backend: "lance"`.
+ *
+ * Choose it when the corpus is large enough that SQLite plus sqlite-vec is the
+ * bottleneck and you are willing to feed the index yourself. Stay on the SQLite
+ * default when you want the markdown corpus crawled for you, or text matching on
+ * exact terms: this adapter's `sync()` does nothing and its `search()` is
+ * vector-only, so a query that would have matched by keyword now has to match by
+ * meaning.
+ *
+ * Requires `@lancedb/lancedb`, an optional peer dependency. It is loaded when
+ * the index is opened, not here.
+ *
+ * Two behaviours are worth knowing before switching. Facts only enter the index
+ * through `unwrap().addFacts(...)` — nothing else writes to it. And `search()`
+ * always queries the `default` namespace, because `SearchOptions` has no
+ * namespace field to pass through, so a multi-tenant caller must open one index
+ * per tenant rather than relying on the filter.
+ */
 export declare class LanceMemoryAdapter implements MemoryIndex {
     private readonly inner;
     constructor(inner: LanceIndex);

package/dist/internal/index/lance-memory-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lance-memory-adapter.d.ts","sourceRoot":"","sources":["../../../src/internal/index/lance-memory-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC/F,OAAO,EAAE,KAAK,WAAW,EAAsB,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE1F;;;;;;;;;;;;;;;;;GAiBG;AACH,UAAU,UAAU;IAClB,QAAQ,CACN,KAAK,EAAE,aAAa,CAAC;QACnB,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC;QACvC,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC,GACD,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,MAAM,CACJ,KAAK,EAAE,MAAM,EACb,IAAI,EAAE;QACJ,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,aAAa,CAAC,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC,CAAC;KACzD,GACA,OAAO,CACR,aAAa,CAAC;QACZ,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC;QACvC,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;KACf,CAAC,CACH,CAAC;IACF,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/C,WAAW,CAAC,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAqBD,qBAAa,kBAAmB,YAAW,WAAW;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,UAAU;IAE9C;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,UAAU,CAAC;IAO3B,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAepF,MAAM,IAAI,WAAW;IAWf,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;;OAGG;IACH,MAAM,IAAI,UAAU;CAGrB"}
+{"version":3,"file":"lance-memory-adapter.d.ts","sourceRoot":"","sources":["../../../src/internal/index/lance-memory-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC/F,OAAO,EAAE,KAAK,WAAW,EAAsB,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE1F;;;;;;;;;;;;;;;;;GAiBG;AACH,UAAU,UAAU;IAClB,QAAQ,CACN,KAAK,EAAE,aAAa,CAAC;QACnB,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC;QACvC,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC,GACD,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,MAAM,CACJ,KAAK,EAAE,MAAM,EACb,IAAI,EAAE;QACJ,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,aAAa,CAAC,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC,CAAC;KACzD,GACA,OAAO,CACR,aAAa,CAAC;QACZ,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC;QACvC,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;KACf,CAAC,CACH,CAAC;IACF,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/C,WAAW,CAAC,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAqBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,kBAAmB,YAAW,WAAW;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,UAAU;IAE9C;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,UAAU,CAAC;IAO3B,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAepF,MAAM,IAAI,WAAW;IAWf,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;;OAGG;IACH,MAAM,IAAI,UAAU;CAGrB"}

package/dist/internal/index/memory-index.d.ts

@@ -31,6 +31,12 @@
  * @internal
  */
 import type { IndexStatus, MemorySearchHit, SearchOptions } from "./index-manager-contract.js";
+/**
+ * What one `sync()` did. `filesScanned` counts every markdown file discovered,
+ * including the unchanged ones; `filesUpdated` counts only those whose content
+ * hash moved. `chunksEmbedded` is 0 on an index with no embedding runtime, and
+ * also on a hybrid index where every chunk already had a vector.
+ */
 export interface SyncResult {
     filesScanned: number;
     filesUpdated: number;
@@ -47,6 +53,15 @@ export declare function parseSearchOptions(options?: SearchOptions): {
     maxResults: number;
     minScore: number;
 };
+/**
+ * The four operations both backends implement, and the type every consumer
+ * should hold. `IndexManager.open` returns this rather than a concrete class
+ * precisely so `backend: "lance"` can be swapped in without changing the caller.
+ *
+ * The two backends differ in what they can honour, and the differences are
+ * visible in the results rather than in the types — see `sync` and `search`
+ * below, and `LanceMemoryAdapter` for the full list.
+ */
 export interface MemoryIndex {
     /**
      * Walk the memory corpus + reindex changed files. Lance backend has no
@@ -56,8 +71,8 @@ export interface MemoryIndex {
     sync(): Promise<SyncResult>;
     /**
      * Semantic + textual search over the indexed corpus. Both backends
-     * return the same `MemorySearchHit[]` shape; Lance leaves `textScore`
-     * undefined (vector-only — no FTS5 layer).
+     * return the same `MemorySearchHit[]` shape; Lance reports `textScore` as 0
+     * on every hit, because it is vector-only and has no FTS5 layer.
      */
     search(query: string, options?: SearchOptions): Promise<MemorySearchHit[]>;
     /** Snapshot of the index health (backend type + counts). */

package/dist/internal/index/memory-index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory-index.d.ts","sourceRoot":"","sources":["../../../src/internal/index/memory-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAW/F,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,aAAkB,GAAG;IAC/D,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAKA;AAED,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;IAE5B;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;IAE3E,4DAA4D;IAC5D,MAAM,IAAI,WAAW,CAAC;IAEtB,0CAA0C;IAC1C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC/B"}
+{"version":3,"file":"memory-index.d.ts","sourceRoot":"","sources":["../../../src/internal/index/memory-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAW/F;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,aAAkB,GAAG;IAC/D,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAKA;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;IAE5B;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;IAE3E,4DAA4D;IAC5D,MAAM,IAAI,WAAW,CAAC;IAEtB,0CAA0C;IAC1C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC/B"}

package/dist/internal/index/migrate-sqlite-to-lance.d.ts

@@ -23,6 +23,18 @@ export interface MigrateOptions {
     /** Inject for tests; defaults to console.log. */
     logger?: (msg: string) => void;
 }
+/**
+ * Outcome of {@link migrateSqliteToLance}.
+ *
+ * Read `committed` first: it is `false` for a dry run and for a failed
+ * validation, and only `true` when the staging directory was promoted to
+ * `lance/`. `validated` reports whether the counts matched and the sampled facts
+ * compared equal; `sampleComparisons` holds up to ten of those comparisons so a
+ * failure can be inspected rather than merely counted.
+ *
+ * The SQLite database is left in place either way — this migration copies, it
+ * does not move.
+ */
 export interface MigrateResult {
     countSqlite: number;
     countLance: number;

package/dist/internal/index/migrate-sqlite-to-lance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migrate-sqlite-to-lance.d.ts","sourceRoot":"","sources":["../../../src/internal/index/migrate-sqlite-to-lance.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,SAAS,EAAE,OAAO,CAAC;IACnB,gEAAgE;IAChE,iBAAiB,EAAE,aAAa,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACjE,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,SAAS,EAAE,OAAO,CAAC;CACpB;AA0DD;;;;;;GAMG;AAEH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAmJvF"}
+{"version":3,"file":"migrate-sqlite-to-lance.d.ts","sourceRoot":"","sources":["../../../src/internal/index/migrate-sqlite-to-lance.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,SAAS,EAAE,OAAO,CAAC;IACnB,gEAAgE;IAChE,iBAAiB,EAAE,aAAa,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACjE,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,SAAS,EAAE,OAAO,CAAC;CACpB;AA0DD;;;;;;GAMG;AAEH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAmJvF"}

package/dist/internal/index/migration.d.ts

@@ -1,9 +1,35 @@
 import { type MemoryConfig } from "../memory-types.js";
+/**
+ * Outcome of {@link migrateLegacyJson}. `reason` is present on every non-migrated
+ * result and says which guard stopped it: `already-migrated` (this key was
+ * attempted earlier in this process), `no-legacy-json` (nothing to migrate, or
+ * the file could not be read or parsed), `markdown-exists` (both files present,
+ * so neither was touched), `readonly-fs` (the write failed).
+ */
 export interface MigrationResult {
     migrated: boolean;
     factCount: number;
     reason?: "already-migrated" | "no-legacy-json" | "markdown-exists" | "readonly-fs";
 }
+/**
+ * Move facts from the pre-markdown JSON store into `MEMORY.md`, once.
+ *
+ * It runs only when the legacy file exists and `MEMORY.md` does not. When both
+ * exist it stops and leaves both alone — merging would need a conflict rule
+ * nobody has picked, and losing hand-written notes is worse than skipping. On
+ * success each fact is appended as a `## Facts` bullet and the JSON file is
+ * deleted.
+ *
+ * Guarded by a per-process set keyed on cwd, namespace, scope and user id, so
+ * the second call for the same key returns `already-migrated` without touching
+ * disk — including after a genuine failure. That set is per module instance, so
+ * a process that loads both this package's copy and the one inside
+ * `@theokit/sdk` has two independent sets.
+ *
+ * Never throws: a JSON file that cannot be read or parsed reports
+ * `no-legacy-json`, and a failed write reports `readonly-fs` after a warning on
+ * stderr.
+ */
 export declare function migrateLegacyJson(cwd: string, config: MemoryConfig): Promise<MigrationResult>;
 /** Test-only — reset the in-process migration flag map. */
 export declare function resetMigrationStateForTests(): void;

package/dist/internal/index/migration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migration.d.ts","sourceRoot":"","sources":["../../../src/internal/index/migration.ts"],"names":[],"mappings":"AACA,OAAO,EAAwB,KAAK,YAAY,EAAmB,MAAM,oBAAoB,CAAC;AAqE9F,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,kBAAkB,GAAG,gBAAgB,GAAG,iBAAiB,GAAG,aAAa,CAAC;CACpF;AAED,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,eAAe,CAAC,CAmB1B;AAED,2DAA2D;AAC3D,wBAAgB,2BAA2B,IAAI,IAAI,CAElD"}
+{"version":3,"file":"migration.d.ts","sourceRoot":"","sources":["../../../src/internal/index/migration.ts"],"names":[],"mappings":"AACA,OAAO,EAAwB,KAAK,YAAY,EAAmB,MAAM,oBAAoB,CAAC;AAqE9F;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,kBAAkB,GAAG,gBAAgB,GAAG,iBAAiB,GAAG,aAAa,CAAC;CACpF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,eAAe,CAAC,CAmB1B;AAED,2DAA2D;AAC3D,wBAAgB,2BAA2B,IAAI,IAAI,CAElD"}