@theokit/sdk 0.0.0-compat-580-20260905204608

package/dist/internal/memory/dreaming/diary.d.ts

@@ -0,0 +1,41 @@
+import type { MemoryRoot } from "../storage/memory-root.js";
+/**
+ * Dream-diary append (ADR D7).
+ *
+ * Diary lives at `.theokit/memory/dream-diary.md` and grows with one entry
+ * per sweep. Each entry is content-hashed so the same input produces the
+ * same entry — idempotency contract.
+ *
+ * Writes go through `replaceFileAtomic` (EC-3 of edge-case review) so a
+ * crash mid-write can never leave a half-written diary.
+ *
+ * Shared with `@theokit/sdk-memory`; see the memory-store barrel.
+ */
+export interface DiaryEntry {
+    timestampMs: number;
+    factsBefore: number;
+    factsAfter: number;
+    duplicatesRemoved: number;
+    clustersCreated: number;
+    notesWritten: number;
+}
+/** `<memory root>/dream-diary.md`. Takes the RESOLVED ROOT — see `storage/memory-root.ts` (#463). */
+export declare function diaryPath(root: MemoryRoot): string;
+/**
+ * One diary entry as the markdown that gets appended: a timestamp heading, the short entry hash,
+ * and the counts the sweep produced. The hash is what makes a re-run recognisable as the same
+ * sweep rather than a new one.
+ */
+export declare function renderDiaryEntry(entry: DiaryEntry): string;
+/**
+ * Append one sweep's entry to `<memory root>/dream-diary.md`, creating the file with its header
+ * when this is the first sweep. The diary is a human-readable record of what dreaming changed —
+ * consolidations are otherwise invisible, because they alter the notes rather than announce
+ * themselves.
+ */
+export declare function appendDiaryEntry(root: MemoryRoot, entry: DiaryEntry): Promise<void>;
+/**
+ * A stable hash of one entry's counts, so two sweeps that did the same work read as the same work.
+ * Rendered truncated in the entry; the full value is what callers compare.
+ */
+export declare function entryHash(entry: DiaryEntry): string;

package/dist/internal/memory/dreaming/phases.d.ts

@@ -0,0 +1,35 @@
+import type { EmbeddingRuntime } from "../embedding-adapter.js";
+import type { MemoryFact } from "../types.js";
+export interface Cluster {
+    representativeText: string;
+    members: ReadonlyArray<MemoryFact>;
+}
+export interface ClusterResult {
+    clusters: Cluster[];
+}
+/**
+ * Light phase — drop facts whose embedding is too similar to one already kept.
+ *
+ * Protected kinds bypass deduplication entirely and are returned untouched, so a sweep can
+ * never conflate two of them into one representative.
+ *
+ * "Drop" here means DROPPED FROM THE RETURNED LIST. Nothing on disk is deleted, by any phase of
+ * this sweep, today.
+ *
+ * BEFORE YOU ADD PRUNING HERE, READ THIS. The security contract for this store requires a backup
+ * to precede any destructive operation (SOP-06-05 step 7). That requirement is currently LATENT
+ * — not satisfied, not waived — precisely because the sweep only ever adds notes and filters a
+ * list. There is no backup implementation in this package, and an audit that looked for one
+ * recorded its absence as having no present consequence.
+ *
+ * The first commit that makes this sweep delete a file from disk is the commit that makes the
+ * gap real, and it is also the commit whose author will have no reason to know this line exists.
+ * That is why the trigger is written beside the code that would trip it rather than in the audit
+ * that found it: a gap recorded in a reviewer's file reappears as a surprise; a gap recorded
+ * here stops the person adding pruning.
+ */
+export declare function lightPhase(facts: ReadonlyArray<MemoryFact>, embedding: EmbeddingRuntime, threshold?: number): Promise<DedupResult>;
+/** REM phase — single-link agglomerative clustering by cosine similarity. */
+export declare function remPhase(facts: ReadonlyArray<MemoryFact>, embedding: EmbeddingRuntime, threshold?: number, maxFactsPerSweep?: number): Promise<ClusterResult>;
+/** Deep phase — render consolidated markdown for the dreamed note. */
+export declare function deepPhase(clusters: ReadonlyArray<Cluster>, timestampMs: number): string;

package/dist/internal/memory/dreaming/run.d.ts

@@ -0,0 +1,10 @@
+export interface DreamingResult {
+    status: "ok" | "skipped" | "error";
+    factsBefore: number;
+    factsAfter: number;
+    duplicatesRemoved: number;
+    clustersCreated: number;
+    notesWritten: number;
+    diaryEntryHash: string | undefined;
+}
+export declare function runDreamingSweep(options: DreamingOptions): Promise<DreamingResult>;

package/dist/internal/memory/embedding-adapter.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Memory embedding provider adapter contract (ADR D3 of memory-system-peer-project-parity).
+ *
+ * Mirrors peer-project's `MemoryEmbeddingProviderAdapter` from
+ * `reference/peer-project/extensions/openai/memory-embedding-adapter.ts` so
+ * adding a new provider becomes one new file under `adapters/`.
+ *
+ * @internal
+ */
+export interface CreateAdapterOptions {
+    /** Override the adapter's `defaultModel`. */
+    model?: string;
+    /** Override the API key (else resolved from env). */
+    apiKey?: string;
+    /** Override the HTTP base URL (else provider default). */
+    baseUrl?: string;
+    /** Inject a fetch implementation (tests use this to stub HTTP). */
+    fetch?: typeof fetch;
+    /** Optional cache instance (else a default LRU is created). */
+    cache?: EmbeddingCache;
+}
+export interface EmbeddingRuntime {
+    readonly id: string;
+    readonly model: string;
+    readonly dimension: number;
+    /** Embed N texts → N vectors of length `dimension`. Handles batching internally. */
+    embed(texts: ReadonlyArray<string>): Promise<number[][]>;
+    /** Observability — cache hit/miss + call counts. */
+    stats(): EmbeddingRuntimeStats;
+}
+export interface EmbeddingRuntimeStats {
+    cacheHits: number;
+    cacheMisses: number;
+    httpCalls: number;
+    retries: number;
+}
+export interface EmbeddingCache {
+    get(key: string): number[] | undefined;
+    set(key: string, value: number[]): void;
+    /** Total entries currently held. */
+    size(): number;
+}

package/dist/internal/memory/embedding-cache.d.ts

@@ -0,0 +1,42 @@
+import type { EmbeddingCache } from "./embedding-adapter.js";
+/**
+ * Bounded in-memory LRU cache for embeddings, keyed by `sha256(text)` (or any
+ * stable key the caller chooses).
+ *
+ * Recency is tracked by Map insertion order: `get` re-inserts the hit so it becomes the newest,
+ * and `set` evicts the oldest key once `capacity` (default 5000) is reached. Nothing here bounds
+ * the size of a single VALUE, so capacity is a count of vectors, not a memory budget.
+ *
+ * Semver-exempt: reachable via the `@theokit/sdk/internal/memory-adapters` sub-path, which the
+ * package declares in `exports` but does NOT cover with its semver contract.
+ */
+export declare class LruEmbeddingCache implements EmbeddingCache {
+    private readonly capacity;
+    private readonly map;
+    constructor(capacity?: number);
+    get(key: string): number[] | undefined;
+    set(key: string, value: number[]): void;
+    size(): number;
+}
+/**
+ * T4.4 — Process-wide singleton embedding cache (DR4 finding #4).
+ *
+ * Pre-T4.4 each adapter / index-manager constructed its own
+ * `LruEmbeddingCache` — a consumer with 3 Memory.openIndex calls
+ * got 3 independent caches with no cross-index deduplication. The
+ * same text embedded identically across indexes re-computed the
+ * embedding each time.
+ *
+ * The singleton shares the cache process-wide so hit rate goes up
+ * dramatically. The LRU eviction (default 5000 entries) bounds
+ * memory usage even with the shared surface.
+ *
+ * Consumers who need isolation (e.g., multi-tenant with different
+ * embedding models) should construct their own `LruEmbeddingCache`
+ * and pass it explicitly — the singleton is the DEFAULT, not the
+ * only option.
+ *
+ * Semver-exempt: reachable via the `@theokit/sdk/internal/memory-adapters` sub-path, which the
+ * package declares in `exports` but does NOT cover with its semver contract.
+ */
+export declare const globalEmbeddingCache: EmbeddingCache;

package/dist/internal/memory/escape-like-pattern.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Escapes a user query for a SQL `LIKE ... ESCAPE '\'` clause.
+ *
+ * The order of the three replacements is the whole correctness argument, so it is its own
+ * function rather than a chain inline at the call site.
+ *
+ * The previous version escaped `%` and `_` but not the escape character itself, which is the
+ * defect CodeQL reports as `js/incomplete-sanitization` (alerts #14, #15). Two things went wrong,
+ * and the second is the one that matters:
+ *
+ *   "back\slash"  ->  "%back\slash%"    the `\s` is an escape of `s`, which LIKE does not define
+ *   "x\%y"        ->  "%x\\%y%"         the inserted `\` is consumed escaping the user's `\`,
+ *                                       leaving `%` UNESCAPED — a wildcard the caller did not
+ *                                       write, matching anything between `x\` and `y`
+ *
+ * The second is wildcard injection: a search for a literal string silently becomes a scan. In a
+ * memory index that is both a wrong answer and a way to pull back rows the query never asked for.
+ *
+ * Escaping the backslash FIRST is what fixes it — afterwards every `\` in the string is one this
+ * function put there, so the later replacements cannot collide with a user-supplied one.
+ */
+export declare function escapeLikePattern(query: string): string;

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

@@ -0,0 +1,67 @@
+import type { MemoryRoot } from "./storage/memory-root.js";
+/**
+ * Memory index DB handle + opener.
+ *
+ * M0-5 (plan m0-foundation-expose-primitives): the driver-load + WAL +
+ * corruption-recovery (EC-7) plumbing is now the shared `openSqliteResilient`
+ * primitive in `internal/persistence`; this module only declares the memory
+ * schema application (PRAGMA + SCHEMA) via its `onOpen` callback.
+ *
+ * Shared with `@theokit/sdk-memory`; see the memory-store barrel.
+ */
+export interface MemoryDb {
+    exec(sql: string): void;
+    prepare(sql: string): {
+        run(...args: unknown[]): {
+            changes: number;
+            lastInsertRowid: number | bigint;
+        };
+        get(...args: unknown[]): Record<string, unknown> | undefined;
+        all(...args: unknown[]): Array<Record<string, unknown>>;
+    };
+    /** SQLite `pragma()` access (used by `applyWalWithFallback`). */
+    pragma(statement: string, options?: {
+        simple?: boolean;
+    }): unknown;
+    close(): void;
+    /**
+     * Load a SQLite loadable extension at the given path.
+     *
+     * NOTHING IN THIS PACKAGE CALLS IT, and it is not dead. The caller is the `sqlite-vec` package:
+     * `loadSqliteVecExtension` hands it this handle and its `load()` does
+     * `db.loadExtension(getLoadablePath())` (sqlite-vec@0.1.9 index.mjs:44). An audit read the absent
+     * in-repo call site as "dead surface that only exists to be refused" and recommended deleting the
+     * member — which would have removed the contract a third-party library depends on. Saying who
+     * calls it is what makes that reading impossible next time.
+     *
+     * On the `node:sqlite` fallback the adapter's Proxy answers with a throwing stub, and that is also
+     * deliberate: the throw is caught by `loadSqliteVecExtension` and becomes a
+     * `ConfigurationError` with code `sqlite_vec_unavailable`, so the bare `Error` never escapes to a
+     * consumer. The stub's message is what ends up as that error's cause.
+     */
+    loadExtension(path: string): void;
+}
+export interface OpenDbOptions {
+    filePath: string;
+    /**
+     * When true and opening fails with a corruption error, rename the file aside
+     * and create a fresh DB. Default true.
+     */
+    recoverCorrupt?: boolean;
+}
+export declare function openMemoryDb(opts: OpenDbOptions): Promise<MemoryDb>;
+/**
+ * `<index root>/.index/memory.sqlite`. Pure path computation.
+ *
+ * Takes a resolved root rather than a `cwd`: this function used to spell the default layout out
+ * again as a string literal — an answer to "where does memory live?" that no search for the shared
+ * helper would have found (#463).
+ *
+ * **The root it is given is the PROJECT store, even when the facts move.** `memory.directory` may
+ * point at the directory the Claude Code CLI manages, and that CLI has no index format — putting a
+ * binary artefact it does not understand inside a directory it owns is a different decision from
+ * putting the facts there, and it was made deliberately. The facts are what a user would lose; the
+ * index is derived and rebuildable from them. See `docs/memory-decisions.md` § 1 before relocating
+ * this, and `IndexManager.openSqliteInternal` for the caller that keeps the two apart.
+ */
+export declare function defaultIndexPath(root: MemoryRoot): string;

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

@@ -0,0 +1,48 @@
+import type { EmbeddingRuntime } from "./embedding-adapter.js";
+import type { MemoryRoot } from "./storage/memory-root.js";
+export interface IndexStatus {
+    backend: "fts-only" | "hybrid";
+    filesIndexed: number;
+    chunksIndexed: number;
+    lastSyncMs?: number;
+    /**
+     * Whether `filesIndexed` / `chunksIndexed` were MEASURED, or are placeholders.
+     *
+     * `IndexManager` counts rows with `SELECT COUNT(*)` and reports `true`. `LanceMemoryAdapter`
+     * reports `false`: its backing store is async and `status()` is not, so it hardcoded zeros while
+     * claiming `backend: "hybrid"` — and a caller deciding "is the index populated?" from
+     * `chunksIndexed > 0` got a false negative on every run, however many rows the table held.
+     *
+     * The zeros stay zero. Inventing a count would trade one false claim for another; what this flag
+     * fixes is a caller reading a placeholder as a measurement.
+     */
+    countsExact: boolean;
+}
+export interface SearchOptions {
+    maxResults?: number;
+    minScore?: number;
+    sources?: ReadonlyArray<"memory" | "sessions" | "wiki">;
+    /** 0..1 — vector vs text weight in hybrid scoring (D4). Default 0.6. */
+    vectorWeight?: number;
+    /** 0..1 — text weight in hybrid scoring. Default 0.4. */
+    textWeight?: number;
+}
+/** Vector backend selector. SQLite default; Lance opt-in (ADR D43). */
+export type MemoryBackend = "sqlite-vec" | "lance";
+export interface OpenIndexOptions {
+    cwd: string;
+    /**
+     * The memory root to index and to place the database under. Defaults to `<cwd>/.theokit/memory`.
+     *
+     * Optional HERE and required everywhere below, deliberately. This is a public entry point whose
+     * caller may legitimately have only a workspace; inside an agent the root is resolved once from
+     * `memory.directory` and passed in, which is what keeps the index and the writer looking at the
+     * same directory (#463).
+     */
+    memoryRoot?: MemoryRoot;
+    filePath?: string;
+    /** When provided, vector index is enabled in hybrid mode. */
+    embedding?: EmbeddingRuntime;
+    /** Vector backend. Default and only value today: `"sqlite-vec"`. */
+    backend?: MemoryBackend;
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Dispatch helpers for `IndexManager.open`. Extracted to keep
+ * `index-manager.ts` under the G8 400-LoC budget (lancedb-backend-ship-v1-1).
+ *
+ * @internal
+ */
+import type { MemoryBackend, OpenIndexOptions } from "./index-manager-contract.js";
+import type { MemoryIndex } from "./memory-index.js";
+/** Valid backend identifiers — runtime guard against TS-narrowing escapes (EC-1). */
+export declare const VALID_BACKENDS: readonly MemoryBackend[];
+/**
+ * EC-1: runtime guard for `opts.backend`. TS union is compile-time only;
+ * consumers passing JS `as any` typos must hit a typed error, not silent
+ * SQLite fallback.
+ */
+export declare function assertValidBackend(backend: string): asserts backend is MemoryBackend;
+/**
+ * Lance-path open. Throws `lance_requires_embedding` when no embedding
+ * runtime is provided (Lance is vector-only — no FTS fallback).
+ * Surfaces `lance_backend_unavailable` from LanceIndex.open when peer
+ * dep is absent.
+ */
+export declare function openLanceIndex(opts: OpenIndexOptions): Promise<MemoryIndex>;

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

@@ -0,0 +1,20 @@
+import type { MemoryRoot } from "./storage/memory-root.js";
+/**
+ * One markdown file the corpus walk found, with the source bucket the indexer tags it with.
+ * Shared through the semver-exempt `internal/memory-store` sub-path, so it carries no
+ * visibility tag — see that barrel for why naming the tag here would delete this symbol.
+ */
+export interface DiscoveredFile {
+    absolutePath: string;
+    relPath: string;
+    source: "memory" | "wiki" | "sessions";
+}
+/**
+ * Every markdown file the memory corpus holds: the index, the per-memory files, `notes/`,
+ * `wiki/` and `sessions/`, each tagged with the bucket `memory_search`'s `corpus` filters on.
+ *
+ * Shared through the semver-exempt `internal/memory-store` sub-path so `@theokit/sdk-memory` walks
+ * the same corpus. Its own copy did not: it never picked up the per-memory files at the root, so
+ * installing that package made every converged memory unsearchable and reported nothing.
+ */
+export declare function collectMarkdownFiles(root: MemoryRoot): Promise<DiscoveredFile[]>;

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

@@ -0,0 +1,44 @@
+import type { SyncResult } from "./memory-index.js";
+import { type MemoryIndex } from "./memory-index.js";
+import type { IndexStatus, MemorySearchHit, OpenIndexOptions, SearchOptions } from "./index-manager-contract.js";
+export declare class IndexManager implements MemoryIndex {
+    private readonly memoryRoot;
+    private readonly db;
+    private readonly embedding;
+    private lastSyncMs;
+    private vectorReady;
+    /** Every SQL string this class used to hold. See `index-repository.ts` for why it moved. */
+    private readonly repo;
+    private constructor();
+    /**
+     * Open a memory index. Dispatches to SQLite (default) or Lance (opt-in
+     * via `backend: "lance"`). See `openLanceInternal` for Lance-specific
+     * preconditions + typed errors.
+     */
+    static open(opts: OpenIndexOptions & {
+        backend: "lance";
+    }): Promise<MemoryIndex>;
+    static open(opts: Omit<OpenIndexOptions, "backend"> | (OpenIndexOptions & {
+        backend?: "sqlite-vec";
+    })): Promise<IndexManager>;
+    /** Internal SQLite-path open. Renamed from previous public `open`. */
+    private static openSqliteInternal;
+    private initVectorBackend;
+    /** Walk the memory corpus + (re)index changed files. */
+    sync(): Promise<SyncResult>;
+    search(query: string, options?: SearchOptions): Promise<MemorySearchHit[]>;
+    status(): IndexStatus;
+    private ftsSearch;
+    /**
+     * T4.8 — LIKE-based fallback for CJK and other scripts that FTS5's
+     * default tokenizer cannot segment. Slower than FTS5 (full table scan)
+     * but correct for any Unicode input. Returns the same shape as
+     * `ftsSearch` so callers are unaware of the fallback.
+     */
+    private likeSearchFallback;
+    private vectorSearchById;
+    private combineHybridScores;
+    private mergeHits;
+    private fetchChunksByIds;
+    close(): void;
+}

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

@@ -0,0 +1,58 @@
+/**
+ * Every SQL string the memory index runs, in one place.
+ *
+ * `IndexManager` answered four questions with four independent reasons to change: the corpus walk,
+ * the BM25-to-score normalisation, the vector-cache strategy, and the schema. This is the fourth.
+ * Changing a column, an index or a join is now a change to THIS file, and the caller above it reads
+ * as search logic rather than as SQL with scoring in between.
+ *
+ * The row-to-`MemorySearchHit` mapping deliberately stays with the caller: turning a row into a hit
+ * involves a score, a snippet and a citation, none of which the schema knows about. Keeping it here
+ * would move the normalisation into the repository and re-create the same mixture one layer down.
+ *
+ * Rows come back as `Record<string, unknown>` for the same reason: the repository knows what it
+ * SELECTed, not what the caller will make of it.
+ *
+ * @internal
+ */
+/** What `files` holds for one path — the pair the corpus walk compares against disk. */
+export interface FileRow {
+    readonly id: number;
+    readonly hash: string;
+}
+export declare class MemoryIndexRepository {
+    private readonly db;
+    constructor(db: MemoryDb);
+    counts(): {
+        files: number;
+        chunks: number;
+    };
+    /**
+     * FTS5 match, ordered by bm25. THROWS on an FTS5 error rather than swallowing it — whether that
+     * error means "CJK input the default tokenizer cannot segment" or "the table is missing" is a
+     * judgement the caller makes, and it makes it differently for each.
+     */
+    ftsRows(sanitizedQuery: string, limit: number): Array<Record<string, unknown>>;
+    /** Substring scan — the CJK fallback. No relevance score exists here; the caller supplies one. */
+    likeRows(escapedPattern: string, limit: number): Array<Record<string, unknown>>;
+    /** Hydrate the chunks a vector search returned by id. Empty in, empty out — no query runs. */
+    chunkRowsByIds(ids: ReadonlyArray<number>): Array<Record<string, unknown>>;
+    /** Absolute path → its row, for the corpus walk to compare hashes against disk. */
+    filesByPath(): Map<string, FileRow>;
+    upsertFile(file: {
+        absPath: string;
+        relPath: string;
+        hash: string;
+        mtimeMs: number;
+        source: "memory" | "wiki" | "sessions";
+    }): number;
+    deleteChunksForFile(fileId: number): void;
+    insertChunk(chunk: {
+        fileId: number;
+        startLine: number;
+        endLine: number;
+        text: string;
+        hash: string;
+    }): void;
+    close(): void;
+}

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

@@ -0,0 +1,21 @@
+/**
+ * SQLite schema for the memory index.
+ *
+ * Tables:
+ *   - files      — one row per indexed markdown file (path, mtime, hash).
+ *   - chunks     — one row per chunk produced by `chunkMarkdown`.
+ *   - chunks_fts — FTS5 virtual table mirroring chunks.text for BM25 search.
+ *   - meta       — key/value store; persists the active embedding identity
+ *                  (provider id, model, dimension) so we detect when the
+ *                  index was built against a different embedding setup.
+ *   - embeddings — sqlite-vec virtual table holding the chunk vectors
+ *                  (created on demand by `vec-index.ts`).
+ *
+ * @internal
+ */
+/**
+ * Non-WAL pragmas. WAL is applied separately via
+ * `applyWalWithFallback` (T4.2, ADR D63) so NFS/SMB users get a graceful
+ * DELETE fallback instead of crashing.
+ */
+export declare const PRAGMA_STATEMENTS: ReadonlyArray<string>;

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

@@ -0,0 +1,46 @@
+import type { EmbeddingRuntime } from "./embedding-adapter.js";
+import { type MemoryRoot } from "./storage/memory-root.js";
+export interface LanceFactRecord {
+    id: string;
+    text: string;
+    source: "memory" | "sessions" | "wiki";
+    embedding: ReadonlyArray<number>;
+    namespace: string;
+    scope: string;
+    user_id: string;
+    timestamp: number;
+}
+export interface OpenLanceOptions {
+    cwd: string;
+    /** The resolved memory root. Defaults to `<cwd>/.theokit/memory` (#463). */
+    memoryRoot?: MemoryRoot;
+    embedding: EmbeddingRuntime;
+    /** Override storage location. Default: `<memory root>/lance/`. */
+    storagePath?: string;
+}
+export interface LanceSearchOptions {
+    namespace: string;
+    scope?: string;
+    limit?: number;
+    sources?: ReadonlyArray<"memory" | "sessions" | "wiki">;
+}
+export interface LanceSearchHit {
+    id: string;
+    text: string;
+    source: "memory" | "sessions" | "wiki";
+    namespace: string;
+    scope: string;
+    userId: string;
+    score: number;
+}
+/**
+ * `<memory root>/lance`.
+ *
+ * Takes the RESOLVED ROOT. This used to spell the default layout out again as a string literal,
+ * beside a second copy of the same literal in `open()` — two more answers to "where does memory
+ * live?" that no `memoryDir` search would have surfaced (#463).
+ *
+ * Shared with `@theokit/sdk-memory` through the memory-store barrel, so it carries no
+ * visibility tag — naming that tag in this block would delete the function below it (#463).
+ */
+export declare function lanceStoragePath(root: MemoryRoot): string;

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

@@ -0,0 +1,45 @@
+/**
+ * `LanceMemoryAdapter` — wraps `LanceIndex` to expose the common
+ * `MemoryIndex` interface (sync/search/status/close) so consumers of
+ * `IndexManager.open({ backend: "lance" })` get a drop-in replacement
+ * for the SQLite-backed `IndexManager`.
+ *
+ * Semantic deltas vs SQLite (documented so callers know what to expect):
+ *
+ *  - `sync()` is a NO-OP. Lance is a pure vector store — there is no
+ *    markdown corpus to crawl. It returns zero counts with `supported: false`
+ *    so the result is not mistaken for a sync that found nothing. Consumers
+ *    writing facts hold a `LanceIndex` and call `addFacts` on it; the adapter
+ *    does not hand its adaptee out.
+ *  - `search()` is HYBRID, not vector-only. Lance supplies the vector distance
+ *    and `translateLanceHit` adds a client-side term-overlap ratio (T4.5), so
+ *    `textScore` is a real number in 0..1 and `score` is `0.7 * vectorScore +
+ *    0.3 * textScore` — never `=== vectorScore`. This block said the opposite
+ *    for as long as T4.5 has been shipped, while the docblock 90 lines below
+ *    described the change correctly, so the two halves of one file disagreed
+ *    and the header is the half a caller reads.
+ *  - `status()` reports `backend: "hybrid"` only when an embedding runtime
+ *    is wired (always the case for Lance — embedding is required at open).
+ *    Both counts are 0 with `countsExact: false`: the port declares `status()`
+ *    synchronous and Lance's row count is async, so nothing can be measured
+ *    here. The zeros are placeholders and the flag says which.
+ *
+ * Ships with the lancedb-backend-ship-v1-1 plan (close D12, supersede via
+ * D43). v1.4.0 of `@theokit/sdk`.
+ *
+ * @internal
+ */
+import type { LanceIndex } from "./lance-index.js";
+import { type MemoryIndex, type SyncResult } from "./memory-index.js";
+export declare class LanceMemoryAdapter implements MemoryIndex {
+    private readonly inner;
+    constructor(inner: LanceIndex);
+    /**
+     * Not applicable to Lance — see file header. Returns zero counts with `supported: false` so a
+     * caller can distinguish this from a real sync that found nothing.
+     */
+    sync(): Promise<SyncResult>;
+    search(query: string, options?: SearchOptions): Promise<MemorySearchHit[]>;
+    status(): IndexStatus;
+    close(): Promise<void>;
+}

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

@@ -0,0 +1,67 @@
+/**
+ * Common `MemoryIndex` interface shared between the SQLite-backed
+ * `IndexManager` (default) and the Lance-backed adapter (ADR D43, shipped
+ * v1.4.0 via lancedb-backend-ship-v1-1 plan).
+ *
+ * Consumers (`local-agent-memory.ts`, `active-memory.ts`, `tools.ts`,
+ * `runActiveMemory`) only ever call `sync()`, `search()`, `status()`,
+ * `close()` — the union of those four methods is the portable surface.
+ *
+ * Why a separate file (vs declaring inline in `index-manager.ts`)? D43
+ * promised "extract an abstract `MemoryIndex` interface in
+ * `internal/memory/index-interface.ts`". Keeping the contract physically
+ * separated from one of its implementations preserves OCP — future
+ * backends (Qdrant, PGVector) can land without touching IndexManager.
+ *
+ * @internal
+ */
+export type { IndexStatus, MemorySearchHit, SearchOptions };
+export interface SyncResult {
+    filesScanned: number;
+    filesUpdated: number;
+    chunksWritten: number;
+    chunksEmbedded: number;
+    /**
+     * Whether this backend actually walked a corpus.
+     *
+     * REQUIRED, not optional, and that is the point. `MemoryIndex` has two implementers and consumers
+     * hold the interface: `IndexManager` walks files, and `LanceMemoryAdapter` has no corpus to walk —
+     * it is a vector store fed by explicit `addFacts`. The adapter used to answer with a frozen
+     * all-zeros result, which a caller cannot tell apart from a real sync that found nothing to do.
+     * The comment above it stated that as the intention ("so callers' existing logging does not
+     * break"), which is the substitution defect written down as a feature.
+     *
+     * A required boolean forces every implementer to say which case it is in, and forces the compiler
+     * to notice a new implementer that forgot. An optional flag would have let the next backend
+     * reproduce the silence.
+     */
+    supported: boolean;
+}
+/**
+ * Common search-options parser used by both `IndexManager.search` and
+ * `LanceMemoryAdapter.search`. Returns the normalized cap + minimum-score
+ * floor — eliminates jscpd duplication while keeping per-backend search
+ * logic distinct.
+ */
+export declare function parseSearchOptions(options?: SearchOptions): {
+    maxResults: number;
+    minScore: number;
+};
+export interface MemoryIndex {
+    /**
+     * Walk the memory corpus + reindex changed files. Lance backend has no
+     * markdown corpus to walk — its adapter returns zero counts (no-op) and
+     * relies on explicit `addFact` calls instead.
+     */
+    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).
+     */
+    search(query: string, options?: SearchOptions): Promise<MemorySearchHit[]>;
+    /** Snapshot of the index health (backend type + counts). */
+    status(): IndexStatus;
+    /** Release native handles. Idempotent. */
+    close(): Promise<void> | void;
+}