@theokit/sdk-memory 0.3.1 → 0.3.2

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

@@ -33,44 +33,95 @@ interface MemoryDb {
     loadExtension(path: string): void;
 }
 /**
- * Vector index helpers (ADR D2 + D4 of memory-system-peer-project-parity).
- *
- * Embeddings live in `embeddings(chunk_id, vec)` — a `vec0` virtual table
- * provided by the sqlite-vec extension. Embedding identity (providerId +
- * model + dimension) lives in the `meta` table; mismatches force a full
- * re-embed sweep (EC-1).
- *
- * Iter 67 (Stage 3 source-move #24): hybrid copy from sdk-core's
- * `internal/memory/vec-index.ts`. sdk-core retains its copy for v1.x
- * sqlite-vec back-compat; sdk-memory ships the canonical copy that
- * future `index-manager.ts` move will compose with as a sibling.
- * Dependency chain (both sibling, both moved):
- * - `EmbeddingRuntime` from `./embedding-adapter.js` (moved iter 45)
- * - `MemoryDb` from `./index-db.js` (moved iter 65)
- *
- * @internal
+ * `meta` table key holding the id of the embedding provider that produced the
+ * vectors currently on disk (for example `openai`, `ollama`).
  */
 export declare const META_KEY_PROVIDER_ID = "embedding.providerId";
+/** `meta` table key holding the embedding model id the vectors were produced with. */
 export declare const META_KEY_MODEL = "embedding.model";
+/** `meta` table key holding the vector width the `embeddings` vec0 table was created with. */
 export declare const META_KEY_DIMENSION = "embedding.dimension";
+/**
+ * The three facts that decide whether the vectors already stored are still
+ * usable: who produced them, with which model, at which width. A change in any
+ * of the three invalidates every vector in the index, because embeddings from
+ * different models are not comparable and a different width will not even fit
+ * the vec0 table.
+ */
 export interface EmbeddingIdentity {
     providerId: string;
     model: string;
     dimension: number;
 }
+/**
+ * Read the embedding identity recorded in the `meta` table.
+ *
+ * Returns `undefined` when the index has never been embedded, and also when the
+ * record is incomplete or unusable: any of the three keys missing, or a stored
+ * dimension that is not a finite number greater than zero. Callers treat that as
+ * "no identity" and write a fresh one rather than trying to repair it.
+ */
 export declare function readEmbeddingIdentity(db: MemoryDb): EmbeddingIdentity | undefined;
+/**
+ * Record the embedding identity in the `meta` table, upserting each of the three
+ * keys. Call this after {@link createVectorIndex}, so that a later open can tell
+ * whether the vectors on disk match the runtime it has been handed.
+ */
 export declare function writeEmbeddingIdentity(db: MemoryDb, identity: EmbeddingIdentity): void;
+/**
+ * Compare two embedding identities field by field. All three fields must be
+ * equal; there is no tolerance on dimension, because a mismatch there is a hard
+ * failure at the vec0 table rather than a quality regression.
+ */
 export declare function identityMatches(a: EmbeddingIdentity, b: EmbeddingIdentity): boolean;
+/**
+ * Drop the `embeddings` table, discarding every stored vector. `IndexManager`
+ * calls this when {@link identityMatches} reports that the persisted identity
+ * differs from the embedding runtime it was opened with; the next `sync()` then
+ * re-embeds the whole corpus. The `chunks` and `files` tables are untouched, so
+ * the text index survives the drop.
+ */
 export declare function dropVectorIndex(db: MemoryDb): void;
+/**
+ * Create the `embeddings` vec0 virtual table at the given vector width, if it
+ * does not exist already. Requires the sqlite-vec extension to be loaded into
+ * `db` first (see `loadSqliteVecExtension`) — without it SQLite has no `vec0`
+ * module and the statement fails.
+ *
+ * `IF NOT EXISTS` means this will NOT widen an existing table: to change the
+ * dimension, call {@link dropVectorIndex} first.
+ */
 export declare function createVectorIndex(db: MemoryDb, dimension: number): void;
 /** Pack a Float32Array into a Buffer suitable for sqlite-vec BLOB binding. */
 export declare function packVector(vec: ReadonlyArray<number>): Buffer;
+/**
+ * Store the vector for one chunk, replacing any vector already held for it.
+ *
+ * Implemented as DELETE followed by INSERT because vec0 virtual tables do not
+ * support `ON CONFLICT`. The chunk id is bound as a BigInt: vec0 v0.1.9 rejects
+ * a JavaScript number for its primary-key column.
+ */
 export declare function upsertEmbedding(db: MemoryDb, chunkId: number, vec: ReadonlyArray<number>): void;
+/**
+ * One row of a vec0 KNN result: the chunk id and its raw distance from the query
+ * vector. Distance is the sqlite-vec convention — lower is closer — and is NOT a
+ * similarity score. `IndexManager` maps it to `1 / (1 + distance)` before
+ * blending it with the text score.
+ */
 export interface VectorHitRow {
     chunk_id: number;
     distance: number;
 }
+/**
+ * Run a k-nearest-neighbour query against the `embeddings` table and return the
+ * matches ordered by ascending distance (closest first).
+ *
+ * `query` must have the same width the table was created with. Both the query
+ * vector and `k` are bound in the form vec0 expects — the vector as a packed
+ * Float32 blob, `k` as a BigInt.
+ */
 export declare function vectorSearch(db: MemoryDb, query: ReadonlyArray<number>, k: number): VectorHitRow[];
+/** Inputs for {@link embedMissingChunks}: the open database and the embedding runtime to call. */
 export interface EmbedAllArgs {
     db: MemoryDb;
     runtime: EmbeddingRuntime;

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

@@ -1 +1 @@
-{"version":3,"file":"vec-index.d.ts","sourceRoot":"","sources":["../../../src/internal/index/vec-index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAE1E;;;;;;;;;;;;;;;;GAgBG;AACH,UAAU,QAAQ;IAChB,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,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,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;GAiBG;AAEH,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAC3D,eAAO,MAAM,cAAc,oBAAoB,CAAC;AAChD,eAAO,MAAM,kBAAkB,wBAAwB,CAAC;AAExD,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,QAAQ,GAAG,iBAAiB,GAAG,SAAS,CAYjF;AAED,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAOtF;AAED,wBAAgB,eAAe,CAAC,CAAC,EAAE,iBAAiB,EAAE,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAEnF;AAED,wBAAgB,eAAe,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CAElD;AAED,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAKvE;AAED,8EAA8E;AAC9E,wBAAgB,UAAU,CAAC,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,MAAM,CAI7D;AAED,wBAAgB,eAAe,CAAC,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,IAAI,CAO/F;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,YAAY,CAC1B,EAAE,EAAE,QAAQ,EACZ,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,EAC5B,CAAC,EAAE,MAAM,GACR,YAAY,EAAE,CAWhB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,QAAQ,CAAC;IACb,OAAO,EAAE,gBAAgB,CAAC;CAC3B;AAED,wDAAwD;AACxD,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAmB5E"}
+{"version":3,"file":"vec-index.d.ts","sourceRoot":"","sources":["../../../src/internal/index/vec-index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAE1E;;;;;;;;;;;;;;;;GAgBG;AACH,UAAU,QAAQ;IAChB,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,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,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAiBD;;;GAGG;AACH,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAC3D,sFAAsF;AACtF,eAAO,MAAM,cAAc,oBAAoB,CAAC;AAChD,8FAA8F;AAC9F,eAAO,MAAM,kBAAkB,wBAAwB,CAAC;AAExD;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,QAAQ,GAAG,iBAAiB,GAAG,SAAS,CAYjF;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAOtF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,iBAAiB,EAAE,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAEnF;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CAElD;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAKvE;AAED,8EAA8E;AAC9E,wBAAgB,UAAU,CAAC,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,MAAM,CAI7D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,IAAI,CAO/F;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,EAAE,EAAE,QAAQ,EACZ,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,EAC5B,CAAC,EAAE,MAAM,GACR,YAAY,EAAE,CAWhB;AAED,kGAAkG;AAClG,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,QAAQ,CAAC;IACb,OAAO,EAAE,gBAAgB,CAAC;CAC3B;AAED,wDAAwD;AACxD,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAmB5E"}

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

@@ -1,3 +1,14 @@
+/**
+ * Per-agent memory configuration. `enabled` gates the configuration-aware
+ * accessors (`readFacts`, `appendFact`) — with it `false` they resolve without
+ * touching disk, while the lower-level markdown functions ignore it.
+ *
+ * `namespace`, `scope` and `userId` are only consulted for the legacy JSON path
+ * (see {@link legacyMemoryJsonPath}); the markdown store keeps one `MEMORY.md`
+ * per workspace and does not partition by them. They are treated as
+ * user-supplied and sanitised before they reach a path. `storePath` is treated
+ * as trusted and resolved as given.
+ */
 export interface MemoryConfig {
     enabled: boolean;
     namespace?: string;
@@ -5,6 +16,11 @@ export interface MemoryConfig {
     scope?: "agent" | "user" | "team";
     storePath?: string;
 }
+/**
+ * One remembered statement. `text` is what gets written, embedded and searched;
+ * it passes through secret redaction on the way to disk, so what is stored may
+ * differ from what was passed in.
+ */
 export interface MemoryFact {
     text: string;
     /**
@@ -73,7 +89,7 @@ export interface MemoryReadResult {
     linesReturned: number;
     /** Total lines in the file (after the read). */
     totalLines: number;
-    /** True when fewer lines were returned than the requested `lines` AND EOF was hit. */
+    /** True when content remains after the returned slice, i.e. `remainingLines > 0`. */
     truncated: boolean;
     /** Lines past the returned slice that remain in the file. */
     remainingLines: number;

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

@@ -1 +1 @@
-{"version":3,"file":"memory-types.d.ts","sourceRoot":"","sources":["../../src/internal/memory-types.ts"],"names":[],"mappings":"AA2BA,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,CAElF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,MAAM,CAY9E;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW;IAC1B,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,aAAa,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,sFAAsF;IACtF,SAAS,EAAE,OAAO,CAAC;IACnB,6DAA6D;IAC7D,cAAc,EAAE,MAAM,CAAC;IACvB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;CACd"}
+{"version":3,"file":"memory-types.d.ts","sourceRoot":"","sources":["../../src/internal/memory-types.ts"],"names":[],"mappings":"AA2BA;;;;;;;;;;GAUG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,CAElF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,MAAM,CAY9E;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW;IAC1B,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,aAAa,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,qFAAqF;IACrF,SAAS,EAAE,OAAO,CAAC;IACnB,6DAA6D;IAC7D,cAAc,EAAE,MAAM,CAAC;IACvB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;CACd"}

package/dist/internal/store/chunk-markdown.d.ts

@@ -61,6 +61,23 @@ export interface ChunkMarkdownOptions {
     /** Minimum chars per chunk (avoids splintering tiny lines). Default 80. */
     minChars?: number;
 }
+/**
+ * Split markdown into the chunks that get embedded and searched.
+ *
+ * Boundaries are structural rather than fixed-width: a chunk ends at the next
+ * heading, or at a blank line. Each chunk carries the nearest preceding heading,
+ * so a hit can be cited with the section it came from. A run of text longer than
+ * `maxChars` is then cut at the last whitespace within 200 characters of the
+ * limit, falling back to a hard cut when a single token is longer than that.
+ *
+ * Returns `[]` for empty input. `minChars` on the options is currently not read
+ * — small paragraphs are emitted as their own chunks regardless.
+ *
+ * Line numbers are 1-indexed and inclusive at both ends. They are exact for
+ * normal chunks; for a paragraph that had to be split by length, the numbers are
+ * derived from newline counts within the slice and mark the span the slice came
+ * from rather than a precise per-slice range.
+ */
 export declare function chunkMarkdown(text: string, options?: ChunkMarkdownOptions): MemoryChunk[];
 export {};
 //# sourceMappingURL=chunk-markdown.d.ts.map

package/dist/internal/store/chunk-markdown.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk-markdown.d.ts","sourceRoot":"","sources":["../../../src/internal/store/chunk-markdown.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,UAAU,WAAW;IACnB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,WAAW,oBAAoB;IACnC,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAWD,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAyB,GAAG,WAAW,EAAE,CAY7F"}
+{"version":3,"file":"chunk-markdown.d.ts","sourceRoot":"","sources":["../../../src/internal/store/chunk-markdown.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,UAAU,WAAW;IACnB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,WAAW,oBAAoB;IACnC,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAWD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAyB,GAAG,WAAW,EAAE,CAY7F"}

package/dist/internal/store/markdown-store.d.ts

@@ -1,17 +1,43 @@
 import { type MemoryConfig, type MemoryFact } from "../memory-types.js";
+/**
+ * The memory root for a workspace: `<cwd>/.theokit/memory`. Every other path in
+ * this package is derived from it, and `memory_get` refuses to read outside it.
+ * Pure path computation — nothing is created on disk.
+ */
 export declare function memoryDir(cwd: string): string;
+/** Path to `MEMORY.md`, the single file holding the flat `## Facts` list. Pure path computation. */
 export declare function memoryMdPath(cwd: string): string;
+/**
+ * Path to `<memory root>/notes`, where per-topic notes and the consolidated
+ * notes written by a dreaming sweep live. Pure path computation — the directory
+ * may not exist.
+ */
 export declare function notesDir(cwd: string): string;
 /** Read facts from `MEMORY.md`'s `## Facts` section. Returns `[]` when missing. */
 export declare function readFactsFromMarkdown(cwd: string): Promise<MemoryFact[]>;
 /** Append a fact to `MEMORY.md ## Facts`. Creates the section if missing. Atomic + serialized. */
 export declare function appendFactToMarkdown(cwd: string, fact: MemoryFact): Promise<void>;
+/** One note discovered under `notes/`: its file name without the `.md` suffix, and its absolute path. */
 export interface NoteFile {
     slug: string;
     path: string;
 }
+/**
+ * List the `.md` files directly under `notes/`. Returns `[]` when the directory
+ * does not exist, so a workspace that has never written a note is not an error.
+ * Does not recurse into sub-directories.
+ */
 export declare function listNotes(cwd: string): Promise<NoteFile[]>;
 /** Configuration-aware accessors honoring the existing MemoryConfig contract. */
 export declare function readFacts(cwd: string, config: MemoryConfig): Promise<MemoryFact[]>;
+/**
+ * Append a fact, honouring the `enabled` gate on {@link MemoryConfig}: when
+ * memory is disabled the call resolves without touching disk. This is the entry
+ * point for configuration-aware callers; `appendFactToMarkdown` is the same
+ * write without the gate.
+ *
+ * The write itself is atomic and serialised per memory root, and the fact text
+ * passes through secret redaction first.
+ */
 export declare function appendFact(cwd: string, config: MemoryConfig, fact: MemoryFact): Promise<void>;
 //# sourceMappingURL=markdown-store.d.ts.map

package/dist/internal/store/markdown-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"markdown-store.d.ts","sourceRoot":"","sources":["../../../src/internal/store/markdown-store.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,UAAU,EAAiB,MAAM,oBAAoB,CAAC;AAqCvF,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED,mFAAmF;AACnF,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAQ9E;AAED,kGAAkG;AAClG,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAcjF;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAUhE;AAsCD,iFAAiF;AACjF,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAGxF;AAED,wBAAsB,UAAU,CAC9B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,IAAI,CAAC,CAGf"}
+{"version":3,"file":"markdown-store.d.ts","sourceRoot":"","sources":["../../../src/internal/store/markdown-store.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,UAAU,EAAiB,MAAM,oBAAoB,CAAC;AAqCvF;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED,oGAAoG;AACpG,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED,mFAAmF;AACnF,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAQ9E;AAED,kGAAkG;AAClG,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAcjF;AAED,yGAAyG;AACzG,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAUhE;AAsCD,iFAAiF;AACjF,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAGxF;AAED;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAC9B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,IAAI,CAAC,CAGf"}

package/dist/internal/store/reader.d.ts

@@ -26,7 +26,7 @@ interface MemoryReadResult {
     linesReturned: number;
     /** Total lines in the file (after the read). */
     totalLines: number;
-    /** True when fewer lines were returned than the requested `lines` AND EOF was hit. */
+    /** True when content remains after the returned slice, i.e. `remainingLines > 0`. */
     truncated: boolean;
     /** Lines past the returned slice that remain in the file. */
     remainingLines: number;
@@ -40,8 +40,8 @@ interface MemoryReadResult {
  * - `from` is 1-indexed.
  * - `lines` defaults to 200 (`DEFAULT_MEMORY_READ_LINES`).
  * - Returns up to EOF when the requested slice extends past file end.
- * - Sets `truncated: true` when fewer lines were returned than requested AND
- *   there's still content past the slice. (At EOF, `truncated: false`.)
+ * - Sets `truncated: true` whenever content remains past the returned slice,
+ *   whether or not the slice was shorter than requested. (At EOF, `false`.)
  *
  * Iter 55 (Stage 3 source-move #12): hybrid copy from sdk-core's
  * `internal/memory/storage/reader.ts`. sdk-core retains its copy for
@@ -53,12 +53,35 @@ interface MemoryReadResult {
  * @internal
  */
 export declare const DEFAULT_MEMORY_READ_LINES = 200;
+/**
+ * Inputs for {@link readMemoryFileBounded}. `relPath` is resolved against `cwd`,
+ * and this function performs no containment check of its own — a `relPath`
+ * containing `..` escapes. The `memory_get` tool validates containment before
+ * calling in.
+ *
+ * `from` is 1-indexed and clamped to at least 1; `lines` defaults to 200 and is
+ * clamped to at least 1.
+ */
 export interface ReadFileOptions {
     cwd: string;
     relPath: string;
     from?: number;
     lines?: number;
 }
+/**
+ * Read a bounded slice of a text file and report what was left behind.
+ *
+ * A single trailing newline is not counted as a line, so `totalLines` matches
+ * what an editor shows. `from` past the end of the file is not an error: it
+ * returns an empty slice with `linesReturned: 0`.
+ *
+ * `truncated` means content remains after the returned slice — it is exactly
+ * `remainingLines > 0`. It does not mean fewer lines were returned than
+ * requested: a full 200-line slice of a 1000-line file is `truncated: true`,
+ * and a short slice that reached the end is `truncated: false`.
+ *
+ * Rejects with the underlying filesystem error when the file cannot be read.
+ */
 export declare function readMemoryFileBounded(opts: ReadFileOptions): Promise<MemoryReadResult>;
 export {};
 //# sourceMappingURL=reader.d.ts.map

package/dist/internal/store/reader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reader.d.ts","sourceRoot":"","sources":["../../../src/internal/store/reader.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,UAAU,gBAAgB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,aAAa,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,sFAAsF;IACtF,SAAS,EAAE,OAAO,CAAC;IACnB,6DAA6D;IAC7D,cAAc,EAAE,MAAM,CAAC;IACvB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;;GAkBG;AAEH,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAE7C,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA6B5F"}
+{"version":3,"file":"reader.d.ts","sourceRoot":"","sources":["../../../src/internal/store/reader.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,UAAU,gBAAgB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,aAAa,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,qFAAqF;IACrF,SAAS,EAAE,OAAO,CAAC;IACnB,6DAA6D;IAC7D,cAAc,EAAE,MAAM,CAAC;IACvB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;;GAkBG;AAEH,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAE7C;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA6B5F"}

package/dist/internal/store/session-loader.d.ts

@@ -21,5 +21,10 @@ export interface SessionFile {
     absolutePath: string;
     relPath: string;
 }
+/**
+ * List the session summaries under `sessions/`, with each path expressed
+ * relative to the memory root so the index can store a stable `sessions/<id>.md`.
+ * Returns `[]` when the directory does not exist. Does not recurse.
+ */
 export declare function discoverSessionFiles(cwd: string): Promise<SessionFile[]>;
 //# sourceMappingURL=session-loader.d.ts.map

package/dist/internal/store/session-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-loader.d.ts","sourceRoot":"","sources":["../../../src/internal/store/session-loader.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,WAAW;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAiB9E"}
+{"version":3,"file":"session-loader.d.ts","sourceRoot":"","sources":["../../../src/internal/store/session-loader.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,WAAW;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAiB9E"}

package/dist/internal/store/session-summary-writer.d.ts

@@ -30,7 +30,21 @@ export interface SessionSummaryInput {
     status: "finished" | "running" | "error" | "cancelled";
     at: number;
 }
+/**
+ * Path to `<memory root>/sessions`, where one markdown summary per finished run
+ * is written. `IndexManager.sync()` indexes these with `source: "sessions"`.
+ * Pure path computation.
+ */
 export declare function sessionsDir(cwd: string): string;
+/**
+ * Path of the summary file for a run.
+ *
+ * The run id is sanitised before it reaches the path: every character outside
+ * `[a-zA-Z0-9_-]` becomes an underscore and the result is cut to 128
+ * characters. That keeps a hostile id inside the sessions directory, and it also
+ * means two different ids can collide onto one file — pass ids that are already
+ * within the safe alphabet if that matters.
+ */
 export declare function sessionSummaryPath(cwd: string, runId: string): string;
 /**
  * Write a session summary file. EC-9: a non-finished status returns early

package/dist/internal/store/session-summary-writer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-summary-writer.d.ts","sourceRoot":"","sources":["../../../src/internal/store/session-summary-writer.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,UAAU,GAAG,SAAS,GAAG,OAAO,GAAG,WAAW,CAAC;IACvD,EAAE,EAAE,MAAM,CAAC;CACZ;AAID,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAErE;AAaD;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4BnF"}
+{"version":3,"file":"session-summary-writer.d.ts","sourceRoot":"","sources":["../../../src/internal/store/session-summary-writer.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,UAAU,GAAG,SAAS,GAAG,OAAO,GAAG,WAAW,CAAC;IACvD,EAAE,EAAE,MAAM,CAAC;CACZ;AAID;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAErE;AAaD;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4BnF"}

package/dist/internal/store/transcript-store.d.ts

@@ -32,5 +32,17 @@ export interface ActiveMemoryTranscript {
         snippet: string;
     }>;
 }
+/**
+ * Write one recall transcript to
+ * `<memory root>/transcripts/active-memory/<runId>.json`, creating the parent
+ * directories and replacing the file atomically.
+ *
+ * Never rejects. A failure is reported on stderr and swallowed, because losing a
+ * diagnostic file must not fail the agent run that produced it. That also means
+ * a successful resolution is not evidence the file was written.
+ *
+ * The run id is used verbatim in the file name — unlike the session summary
+ * writer, nothing sanitises it here, so pass an id you control.
+ */
 export declare function persistActiveMemoryTranscript(cwd: string, transcript: ActiveMemoryTranscript): Promise<void>;
 //# sourceMappingURL=transcript-store.d.ts.map

package/dist/internal/store/transcript-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transcript-store.d.ts","sourceRoot":"","sources":["../../../src/internal/store/transcript-store.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,IAAI,EAAE,aAAa,CAAC;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;CACJ;AAED,wBAAsB,6BAA6B,CACjD,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,sBAAsB,GACjC,OAAO,CAAC,IAAI,CAAC,CAWf"}
+{"version":3,"file":"transcript-store.d.ts","sourceRoot":"","sources":["../../../src/internal/store/transcript-store.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,IAAI,EAAE,aAAa,CAAC;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;CACJ;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,6BAA6B,CACjD,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,sBAAsB,GACjC,OAAO,CAAC,IAAI,CAAC,CAWf"}

package/dist/internal/store/wiki-loader.d.ts

@@ -19,6 +19,17 @@ export interface WikiFile {
     absolutePath: string;
     relPath: string;
 }
+/**
+ * Path to `<memory root>/wiki`, the read-only supplement directory. Nothing in
+ * this package writes there — it is for material a human or another tool puts
+ * in place. Pure path computation.
+ */
 export declare function wikiDir(cwd: string): string;
+/**
+ * List the `.md` files directly under `wiki/`, with each path expressed relative
+ * to the memory root so the index can store a stable `wiki/<name>.md`. Returns
+ * `[]` when the directory does not exist. Does not recurse, so wiki material
+ * organised into sub-directories is not picked up.
+ */
 export declare function discoverWikiFiles(cwd: string): Promise<WikiFile[]>;
 //# sourceMappingURL=wiki-loader.d.ts.map

package/dist/internal/store/wiki-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wiki-loader.d.ts","sourceRoot":"","sources":["../../../src/internal/store/wiki-loader.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,QAAQ;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAkBxE"}
+{"version":3,"file":"wiki-loader.d.ts","sourceRoot":"","sources":["../../../src/internal/store/wiki-loader.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,QAAQ;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAkBxE"}

package/dist/internal/tools.d.ts

@@ -28,17 +28,55 @@ export interface MemoryToolJson {
     description: string;
     inputSchema: Record<string, unknown>;
 }
+/**
+ * A memory tool ready to hand to the agent loop: the JSON-serialisable
+ * description an LLM sees, plus the `execute` that runs it. `execute` resolves
+ * to a JSON string — the tool layer does no further encoding.
+ */
 export interface MemoryTool extends MemoryToolJson {
     execute(input: Record<string, unknown>): Promise<string>;
 }
+/** Options for {@link createMemorySearchTool}. */
 export interface MemorySearchToolOptions {
     index: MemoryIndex;
     /** Cap on the JSON response size (EC-10 of edge-case review). Default 16384. */
     maxTotalChars?: number;
 }
+/**
+ * Build the `memory_search` tool over an index that is already open. The tool
+ * never opens or syncs anything: if `index.sync()` has not run, the search runs
+ * against whatever the index last recorded, and a freshly created index returns
+ * no hits.
+ *
+ * The tool accepts `query` (required), `maxResults` (default 10), `minScore`,
+ * and `corpus`, where `corpus` maps to the index's source filter: `memory`,
+ * `sessions`, `wiki`, or `all` (the default, which applies no filter). An
+ * unrecognised `corpus` value is treated as `all` rather than rejected.
+ *
+ * `execute` returns `{"hits": [...], "truncated": bool}`. Hits are dropped from
+ * the tail once their estimated size would exceed `maxTotalChars`, except that
+ * the first hit is always kept even when it alone exceeds the cap.
+ *
+ * Use this for recall by meaning across the whole corpus, and
+ * {@link createMemoryGetTool} when the model already knows the file and wants
+ * exact lines.
+ */
 export declare function createMemorySearchTool(opts: MemorySearchToolOptions): MemoryTool;
+/** Options for {@link createMemoryGetTool}. `cwd` is the workspace root, not the memory directory. */
 export interface MemoryGetToolOptions {
     cwd: string;
 }
+/**
+ * Build the `memory_get` tool, which reads an exact excerpt from a file under
+ * `<cwd>/.theokit/memory`. Needs no index and no embedding runtime — it is
+ * plain file reading, so it works in a workspace where search is not configured.
+ *
+ * The tool accepts `path` (required, relative to the memory root), `from`
+ * (1-indexed, default 1) and `lines` (default 200). A `path` whose resolved
+ * location falls outside the memory root is rejected with a
+ * `ConfigurationError` carrying the code `memory_path_escapes_root`. A path that
+ * stays inside but does not exist is not caught here: the underlying read
+ * rejects with the filesystem error.
+ */
 export declare function createMemoryGetTool(opts: MemoryGetToolOptions): MemoryTool;
 //# sourceMappingURL=tools.d.ts.map

package/dist/internal/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/internal/tools.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAI3D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,UAAW,SAAQ,cAAc;IAChD,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1D;AAiCD,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,WAAW,CAAC;IACnB,gFAAgF;IAChF,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,uBAAuB,GAAG,UAAU,CAqBhF;AAED,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;CACb;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,oBAAoB,GAAG,UAAU,CA4B1E"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/internal/tools.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAI3D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAW,SAAQ,cAAc;IAChD,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1D;AAiCD,kDAAkD;AAClD,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,WAAW,CAAC;IACnB,gFAAgF;IAChF,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,uBAAuB,GAAG,UAAU,CAqBhF;AAED,sGAAsG;AACtG,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,oBAAoB,GAAG,UAAU,CA4B1E"}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@theokit/sdk-memory",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Memory subsystem for @theokit/sdk — MemoryProvider impls (markdown file store today; LanceDB + embeddings + circuit breaker next iters). Consumes the kernel-facing port from sdk-core.",
   "license": "Apache-2.0",
-  "homepage": "https://github.com/usetheodev/theokit-sdk#readme",
-  "bugs": "https://github.com/usetheodev/theokit-sdk/issues",
+  "homepage": "https://github.com/usetheokit/theokit-sdk#readme",
+  "bugs": "https://github.com/usetheokit/theokit-sdk/issues",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/usetheodev/theokit-sdk.git",
+    "url": "git+https://github.com/usetheokit/theokit-sdk.git",
     "directory": "packages/sdk-memory"
   },
   "type": "module",
@@ -61,13 +61,14 @@
     "@types/better-sqlite3": "^7.6.13",
     "better-sqlite3": "^12.10.0",
     "sqlite-vec": "^0.1.6",
-    "@theokit/sdk": "4.43.0"
+    "@theokit/sdk": "4.54.0"
   },
   "publishConfig": {
+    "provenance": true,
     "access": "public"
   },
   "scripts": {
-    "build": "tsup && tsc -p tsconfig.build.json && cp dist/index.d.ts dist/index.d.cts",
+    "build": "tsup && tsc -p tsconfig.build.json && cp dist/index.d.ts dist/index.d.cts && node ../../tools/repair-dts-imports.mjs .",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   }

package/dist/internal/active-memory/composite-scorer.d.ts

@@ -1,19 +0,0 @@
-/**
- * Composite scoring — blends semantic, text, recency, and importance signals.
- *
- * Inspired by a peer project's `unified_memory.py` composite scoring (lines 345-381).
- * Default weights: semantic 0.5, text 0.2, recency 0.2, importance 0.1.
- * Backward-compatible: old behavior reproduced with {recencyWeight:0, importanceWeight:0}.
- *
- * @internal
- */
-export interface CompositeScoreConfig {
-    semanticWeight: number;
-    textWeight: number;
-    recencyWeight: number;
-    importanceWeight: number;
-    recencyHalfLifeMs: number;
-}
-export declare const DEFAULT_COMPOSITE_CONFIG: CompositeScoreConfig;
-export declare function compositeScore(vectorScore: number, textScore: number, createdAt: number | null, importance: number, config?: CompositeScoreConfig): number;
-//# sourceMappingURL=composite-scorer.d.ts.map

package/dist/internal/active-memory/composite-scorer.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"composite-scorer.d.ts","sourceRoot":"","sources":["../../../src/internal/active-memory/composite-scorer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,MAAM,WAAW,oBAAoB;IACnC,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,eAAO,MAAM,wBAAwB,EAAE,oBAMtC,CAAC;AAEF,wBAAgB,cAAc,CAC5B,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,UAAU,EAAE,MAAM,EAClB,MAAM,GAAE,oBAA+C,GACtD,MAAM,CAUR"}

package/dist/internal/active-memory/query-analyzer.d.ts

@@ -1,16 +0,0 @@
-/**
- * Query analyzer — LLM-driven sub-query distillation for complex queries.
- *
- * Inspired by a peer project's `recall_flow.py`. Opt-in: short queries (≤250 chars)
- * pass through unchanged. Per ADR D3.
- *
- * @internal
- */
-interface QueryAnalysisResult {
-    subQueries: string[];
-    timeFilter?: number;
-    scopeHint?: string;
-}
-export declare function analyzeQuery(query: string, callLlm: (system: string, user: string) => Promise<string>): Promise<QueryAnalysisResult>;
-export {};
-//# sourceMappingURL=query-analyzer.d.ts.map

package/dist/internal/active-memory/query-analyzer.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"query-analyzer.d.ts","sourceRoot":"","sources":["../../../src/internal/active-memory/query-analyzer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,UAAU,mBAAmB;IAC3B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAsB,YAAY,CAChC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GACzD,OAAO,CAAC,mBAAmB,CAAC,CAmB9B"}

package/dist/internal/embedding/batch-encoder.d.ts

@@ -1,30 +0,0 @@
-/**
- * Batch encoding pipeline — embeds N texts in 1 API call with intra-batch dedup.
- *
- * Inspired by a peer project's `encoding_flow.py` Stage 1-2: batch embed + cosine dedup.
- * Per ADR D1: new module alongside sync(), not a replacement.
- *
- * @internal
- */
-import type { EmbeddingRuntime } from "./embedding-adapter.js";
-interface RememberManyOptions {
-    scope?: string;
-    importance?: number;
-    dedupThreshold?: number;
-}
-interface RememberManyResult {
-    total: number;
-    deduped: number;
-    inserted: number;
-}
-interface KeptItem {
-    text: string;
-    vector: number[];
-}
-declare function cosineSimilarity(a: number[], b: number[]): number;
-export declare function rememberMany(texts: string[], embedding: EmbeddingRuntime, opts?: RememberManyOptions): Promise<{
-    result: RememberManyResult;
-    items: KeptItem[];
-}>;
-export { cosineSimilarity };
-//# sourceMappingURL=batch-encoder.d.ts.map

package/dist/internal/embedding/batch-encoder.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"batch-encoder.d.ts","sourceRoot":"","sources":["../../../src/internal/embedding/batch-encoder.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,UAAU,mBAAmB;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,UAAU,kBAAkB;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,QAAQ;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,iBAAS,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAY1D;AAmBD,wBAAsB,YAAY,CAChC,KAAK,EAAE,MAAM,EAAE,EACf,SAAS,EAAE,gBAAgB,EAC3B,IAAI,GAAE,mBAAwB,GAC7B,OAAO,CAAC;IAAE,MAAM,EAAE,kBAAkB,CAAC;IAAC,KAAK,EAAE,QAAQ,EAAE,CAAA;CAAE,CAAC,CAiB5D;AAED,OAAO,EAAE,gBAAgB,EAAE,CAAC"}

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

@@ -1,21 +0,0 @@
-/**
- * Hierarchical memory scopes — path-based isolation for multi-agent setups.
- *
- * Inspired by a peer project's `MemoryScope` with path hierarchy.
- * Per ADR D4: scope stored as TEXT column, prefix-matched via LIKE.
- *
- * @internal
- */
-export declare function normalizeScopePath(path: string): string;
-interface ScopeSearchOptions {
-    scopePrefix?: string;
-}
-export declare class MemoryScope {
-    private readonly rootPath;
-    constructor(rootPath: string);
-    get path(): string;
-    child(subPath: string): MemoryScope;
-    toSearchOptions(): ScopeSearchOptions;
-}
-export {};
-//# sourceMappingURL=memory-scope.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"memory-scope.d.ts","sourceRoot":"","sources":["../../src/internal/memory-scope.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGvD;AAED,UAAU,kBAAkB;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEtB,QAAQ,EAAE,MAAM;IAI5B,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW;IAKnC,eAAe,IAAI,kBAAkB;CAGtC"}