@theokit/sdk 0.0.0-compat-580-20260905204608

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

@@ -0,0 +1,58 @@
+import { type MemoryRoot } from "./storage/memory-root.js";
+/**
+ * Migrate Memory.index from SQLite to LanceDB (ADR D44).
+ *
+ * EC-3 MUST FIX: validation uses NFC unicode normalization on both sides.
+ *
+ * Shared with `@theokit/sdk-memory` through the memory-store barrel (#463).
+ */
+export interface MigrateOptions {
+    cwd: string;
+    /**
+     * Absolute path (or `~/`-prefixed) of the memory root to migrate, when the agent that wrote it
+     * set `memory.directory`. Defaults to `<cwd>/.theokit/memory` (#463).
+     */
+    directory?: string;
+    dryRun?: boolean;
+    batchSize?: number;
+    /** Inject for tests; defaults to console.log. */
+    logger?: (msg: string) => void;
+}
+export interface MigrateResult {
+    countSqlite: number;
+    countLance: number;
+    /** Set when validation succeeded (or dryRun); false on validation failure. */
+    validated: boolean;
+    /** Per-fact compare results (size = sample count, up to 10). */
+    sampleComparisons: ReadonlyArray<{
+        id: string;
+        match: boolean;
+    }>;
+    /** Lance storage location (final, after migration). */
+    lancePath: string;
+    /** Was the migration committed (false for dry-run). */
+    committed: boolean;
+}
+/**
+ * One row of the SQLite memory index, as the Lance migration reads it: the chunk plus the tenant
+ * columns the target table needs. Shared with `@theokit/sdk-memory`, which migrates the same table.
+ */
+export interface SqliteFactRow {
+    id: string;
+    path: string;
+    source: "memory" | "sessions" | "wiki";
+    start_line: number;
+    end_line: number;
+    text: string;
+    namespace?: string | null;
+    scope?: string | null;
+    user_id?: string | null;
+}
+/**
+ * Read all facts from the SQLite memory index. Returns empty array if the
+ * SQLite db file does not exist (workspace never used Memory).
+ *
+ * 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 readAllSqliteFacts(root: MemoryRoot): Promise<SqliteFactRow[]>;

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

@@ -0,0 +1,9 @@
+import { type MemoryConfig } from "./types.js";
+export interface MigrationResult {
+    migrated: boolean;
+    factCount: number;
+    reason?: "already-migrated" | "no-legacy-json" | "markdown-exists" | "readonly-fs";
+}
+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/memory/sdk-memory-peer-loader.d.ts

@@ -0,0 +1,74 @@
+/**
+ * SDK 2.0 Phase 4 (Stage 4) — Optional peer loader for
+ * `@theokit/sdk-memory`.
+ *
+ * The Memory class public API in `src/memory.ts` keeps its surface
+ * stable but routes through sdk-memory when installed. When sdk-memory
+ * is NOT installed, methods fall back to sdk-core's legacy
+ * `internal/memory/*` implementations — preserving v1.x back-compat.
+ *
+ * Pattern mirrors sdk-handoff's optional-peer dynamic import: try
+ * `await import("@theokit/sdk-memory")` once, cache the result (the
+ * module OR `null` for "definitively missing"), and let the caller
+ * route.
+ *
+ * Iter 76 (Stage 4 #1): foundation helper for the Memory class
+ * delegation refactor. No behavior changes yet — this iter only
+ * adds the loader; iter 77+ wires Memory class methods to use it.
+ *
+ * @internal
+ */
+/**
+ * Minimal structural mirror of the sdk-memory surface this loader
+ * exposes to Memory class methods. Keeps the contract pinned even
+ * if sdk-memory ships additional exports.
+ */
+export interface SdkMemoryModule {
+    /** Mirrors @theokit/sdk-memory's catalog Record. */
+    readonly MEMORY_EMBEDDING_ADAPTERS: Readonly<Record<string, {
+        readonly id: string;
+        readonly defaultModel: string;
+        readonly transport: "local" | "remote";
+        create(options: any): Promise<any>;
+    }>>;
+    /** Mirrors @theokit/sdk-memory's runDreamingSweep entrypoint. */
+    runDreamingSweep(opts: {
+        cwd: string;
+        embedding: any;
+        dedupThreshold?: number;
+        clusterThreshold?: number;
+    }): Promise<{
+        status: "ok" | "skipped" | "error";
+        factsBefore: number;
+        factsAfter: number;
+        duplicatesRemoved: number;
+        clustersCreated: number;
+        notesWritten: number;
+    }>;
+    /** Mirrors @theokit/sdk-memory's IndexManager class (static open). */
+    readonly IndexManager: {
+        open(opts: {
+            cwd: string;
+            filePath?: string;
+            embedding?: any;
+            backend?: "sqlite-vec" | "lance";
+        }): Promise<any>;
+    };
+    /** Mirrors @theokit/sdk-memory's migrateSqliteToLance entrypoint (ADR D44). */
+    migrateSqliteToLance(opts: {
+        cwd: string;
+        dryRun?: boolean;
+        batchSize?: number;
+        logger?: (msg: string) => void;
+    }): Promise<{
+        countSqlite: number;
+        countLance: number;
+        validated: boolean;
+        sampleComparisons: ReadonlyArray<{
+            id: string;
+            match: boolean;
+        }>;
+        lancePath: string;
+        committed: boolean;
+    }>;
+}

package/dist/internal/memory/sqlite-vec-loader.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/memory/storage/chunk-markdown.d.cts

@@ -0,0 +1,2 @@
+import type { MemoryChunk } from "../types.js";
+export declare function chunkMarkdown(text: string, options?: ChunkMarkdownOptions): MemoryChunk[];

package/dist/internal/memory/storage/chunk-markdown.d.ts

@@ -0,0 +1,2 @@
+import type { MemoryChunk } from "../types.js";
+export declare function chunkMarkdown(text: string, options?: ChunkMarkdownOptions): MemoryChunk[];

package/dist/internal/memory/storage/index.cjs

@@ -0,0 +1,141 @@
+'use strict';
+
+var chunkVPK6PHIE_cjs = require('../../../chunk-VPK6PHIE.cjs');
+var chunkTMKTSYDS_cjs = require('../../../chunk-TMKTSYDS.cjs');
+var chunkNQTNSHSB_cjs = require('../../../chunk-NQTNSHSB.cjs');
+require('../../../chunk-KRD3GQAA.cjs');
+require('../../../chunk-MUUQ2WFJ.cjs');
+require('../../../chunk-LOHMT36V.cjs');
+require('../../../chunk-7A6535RA.cjs');
+require('../../../chunk-SA6K24NB.cjs');
+require('../../../chunk-GZV6AVRL.cjs');
+require('../../../chunk-DQZU7JK6.cjs');
+require('../../../chunk-ZF2LDKQQ.cjs');
+require('../../../chunk-JLRLCBJ4.cjs');
+require('../../../chunk-J7J7J2GN.cjs');
+require('../../../chunk-6LHQPOMI.cjs');
+
+
+
+Object.defineProperty(exports, "appendDiaryEntry", {
+  enumerable: true,
+  get: function () { return chunkVPK6PHIE_cjs.appendDiaryEntry; }
+});
+Object.defineProperty(exports, "diaryPath", {
+  enumerable: true,
+  get: function () { return chunkVPK6PHIE_cjs.diaryPath; }
+});
+Object.defineProperty(exports, "entryHash", {
+  enumerable: true,
+  get: function () { return chunkVPK6PHIE_cjs.entryHash; }
+});
+Object.defineProperty(exports, "readAllSqliteFacts", {
+  enumerable: true,
+  get: function () { return chunkVPK6PHIE_cjs.readAllSqliteFacts; }
+});
+Object.defineProperty(exports, "renderDiaryEntry", {
+  enumerable: true,
+  get: function () { return chunkVPK6PHIE_cjs.renderDiaryEntry; }
+});
+Object.defineProperty(exports, "persistActiveMemoryTranscript", {
+  enumerable: true,
+  get: function () { return chunkTMKTSYDS_cjs.persistActiveMemoryTranscript; }
+});
+Object.defineProperty(exports, "MEMORY_INDEX_MAX_BYTES", {
+  enumerable: true,
+  get: function () { return chunkNQTNSHSB_cjs.MEMORY_INDEX_MAX_BYTES; }
+});
+Object.defineProperty(exports, "MEMORY_INDEX_MAX_LINES", {
+  enumerable: true,
+  get: function () { return chunkNQTNSHSB_cjs.MEMORY_INDEX_MAX_LINES; }
+});
+Object.defineProperty(exports, "appendFact", {
+  enumerable: true,
+  get: function () { return chunkNQTNSHSB_cjs.appendFact; }
+});
+Object.defineProperty(exports, "appendFactToMarkdown", {
+  enumerable: true,
+  get: function () { return chunkNQTNSHSB_cjs.appendFactToMarkdown; }
+});
+Object.defineProperty(exports, "asMemoryRoot", {
+  enumerable: true,
+  get: function () { return chunkNQTNSHSB_cjs.asMemoryRoot; }
+});
+Object.defineProperty(exports, "claudeProjectMemoryDir", {
+  enumerable: true,
+  get: function () { return chunkNQTNSHSB_cjs.claudeProjectMemoryDir; }
+});
+Object.defineProperty(exports, "collectMarkdownFiles", {
+  enumerable: true,
+  get: function () { return chunkNQTNSHSB_cjs.collectMarkdownFiles; }
+});
+Object.defineProperty(exports, "defaultIndexPath", {
+  enumerable: true,
+  get: function () { return chunkNQTNSHSB_cjs.defaultIndexPath; }
+});
+Object.defineProperty(exports, "discoverSessionFiles", {
+  enumerable: true,
+  get: function () { return chunkNQTNSHSB_cjs.discoverSessionFiles; }
+});
+Object.defineProperty(exports, "discoverWikiFiles", {
+  enumerable: true,
+  get: function () { return chunkNQTNSHSB_cjs.discoverWikiFiles; }
+});
+Object.defineProperty(exports, "indexBudgetWarning", {
+  enumerable: true,
+  get: function () { return chunkNQTNSHSB_cjs.indexBudgetWarning; }
+});
+Object.defineProperty(exports, "lanceStoragePath", {
+  enumerable: true,
+  get: function () { return chunkNQTNSHSB_cjs.lanceStoragePath; }
+});
+Object.defineProperty(exports, "memoryIndexRoot", {
+  enumerable: true,
+  get: function () { return chunkNQTNSHSB_cjs.memoryIndexRoot; }
+});
+Object.defineProperty(exports, "memoryMdPath", {
+  enumerable: true,
+  get: function () { return chunkNQTNSHSB_cjs.memoryMdPath; }
+});
+Object.defineProperty(exports, "memoryReadRoots", {
+  enumerable: true,
+  get: function () { return chunkNQTNSHSB_cjs.memoryReadRoots; }
+});
+Object.defineProperty(exports, "notesDir", {
+  enumerable: true,
+  get: function () { return chunkNQTNSHSB_cjs.notesDir; }
+});
+Object.defineProperty(exports, "projectMemoryDir", {
+  enumerable: true,
+  get: function () { return chunkNQTNSHSB_cjs.projectMemoryDir; }
+});
+Object.defineProperty(exports, "readFacts", {
+  enumerable: true,
+  get: function () { return chunkNQTNSHSB_cjs.readFacts; }
+});
+Object.defineProperty(exports, "readFactsFromMarkdown", {
+  enumerable: true,
+  get: function () { return chunkNQTNSHSB_cjs.readFactsFromMarkdown; }
+});
+Object.defineProperty(exports, "resolveMemoryRoot", {
+  enumerable: true,
+  get: function () { return chunkNQTNSHSB_cjs.resolveMemoryRoot; }
+});
+Object.defineProperty(exports, "sessionSummaryPath", {
+  enumerable: true,
+  get: function () { return chunkNQTNSHSB_cjs.sessionSummaryPath; }
+});
+Object.defineProperty(exports, "sessionsDir", {
+  enumerable: true,
+  get: function () { return chunkNQTNSHSB_cjs.sessionsDir; }
+});
+Object.defineProperty(exports, "wikiDir", {
+  enumerable: true,
+  get: function () { return chunkNQTNSHSB_cjs.wikiDir; }
+});
+Object.defineProperty(exports, "writeSessionSummary", {
+  enumerable: true,
+  get: function () { return chunkNQTNSHSB_cjs.writeSessionSummary; }
+});
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/internal/memory/storage/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.cjs"}

package/dist/internal/memory/storage/index.d.cts

@@ -0,0 +1,28 @@
+/**
+ * #430 — the ONE markdown memory store, shared with `@theokit/sdk-memory`.
+ *
+ * The satellite carried a full copy, and `Memory.runDreamingSweep` REPLACES this one with the
+ * peer's whenever the peer is installed — so the copy that ran was not the copy most people read.
+ * The copy stayed on the pre-#389 layout (bullets under `MEMORY.md ## Facts`) while this one moved
+ * to a file per memory, which meant installing `@theokit/sdk-memory` made every memory the SDK had
+ * written unreadable. It reported `factsBefore: 0`, indistinguishable from an empty store.
+ *
+ * This is the same defect theokit#160 fixed for the embedding runtime, in the same package pair,
+ * with the same remedy: one implementation, imported by both. A second copy is a second place for
+ * the layout to drift, and the drift is silent by construction — nothing fails, facts just stop
+ * being found.
+ *
+ * Semver-exempt: NOT part of the stable `@theokit/sdk` API. The sub-path IS declared in
+ * `package.json` `exports`, so the names below must survive into the published declarations.
+ */
+export { appendDiaryEntry, type DiaryEntry, diaryPath, entryHash, renderDiaryEntry, } from "../dreaming/diary.js";
+export { defaultIndexPath } from "../index-db.js";
+export { collectMarkdownFiles, type DiscoveredFile } from "../index-manager-helpers.js";
+export { lanceStoragePath } from "../lance-index.js";
+export { readAllSqliteFacts, type SqliteFactRow } from "../migrate-sqlite-to-lance.js";
+export { appendFact, appendFactToMarkdown, memoryMdPath, notesDir, readFacts, readFactsFromMarkdown, } from "./markdown-store.js";
+export { asMemoryRoot, claudeProjectMemoryDir, indexBudgetWarning, MEMORY_INDEX_MAX_BYTES, MEMORY_INDEX_MAX_LINES, type MemoryLocationConfig, type MemoryRoot, memoryIndexRoot, memoryReadRoots, projectMemoryDir, resolveMemoryRoot, } from "./memory-root.js";
+export { discoverSessionFiles, type SessionFile } from "./session-loader.js";
+export { type SessionSummaryInput, sessionSummaryPath, sessionsDir, writeSessionSummary, } from "./session-summary-writer.js";
+export { type ActiveMemoryTranscript, persistActiveMemoryTranscript } from "./transcript-store.js";
+export { discoverWikiFiles, type WikiFile, wikiDir } from "./wiki-loader.js";

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

@@ -0,0 +1,28 @@
+/**
+ * #430 — the ONE markdown memory store, shared with `@theokit/sdk-memory`.
+ *
+ * The satellite carried a full copy, and `Memory.runDreamingSweep` REPLACES this one with the
+ * peer's whenever the peer is installed — so the copy that ran was not the copy most people read.
+ * The copy stayed on the pre-#389 layout (bullets under `MEMORY.md ## Facts`) while this one moved
+ * to a file per memory, which meant installing `@theokit/sdk-memory` made every memory the SDK had
+ * written unreadable. It reported `factsBefore: 0`, indistinguishable from an empty store.
+ *
+ * This is the same defect theokit#160 fixed for the embedding runtime, in the same package pair,
+ * with the same remedy: one implementation, imported by both. A second copy is a second place for
+ * the layout to drift, and the drift is silent by construction — nothing fails, facts just stop
+ * being found.
+ *
+ * Semver-exempt: NOT part of the stable `@theokit/sdk` API. The sub-path IS declared in
+ * `package.json` `exports`, so the names below must survive into the published declarations.
+ */
+export { appendDiaryEntry, type DiaryEntry, diaryPath, entryHash, renderDiaryEntry, } from "../dreaming/diary.js";
+export { defaultIndexPath } from "../index-db.js";
+export { collectMarkdownFiles, type DiscoveredFile } from "../index-manager-helpers.js";
+export { lanceStoragePath } from "../lance-index.js";
+export { readAllSqliteFacts, type SqliteFactRow } from "../migrate-sqlite-to-lance.js";
+export { appendFact, appendFactToMarkdown, memoryMdPath, notesDir, readFacts, readFactsFromMarkdown, } from "./markdown-store.js";
+export { asMemoryRoot, claudeProjectMemoryDir, indexBudgetWarning, MEMORY_INDEX_MAX_BYTES, MEMORY_INDEX_MAX_LINES, type MemoryLocationConfig, type MemoryRoot, memoryIndexRoot, memoryReadRoots, projectMemoryDir, resolveMemoryRoot, } from "./memory-root.js";
+export { discoverSessionFiles, type SessionFile } from "./session-loader.js";
+export { type SessionSummaryInput, sessionSummaryPath, sessionsDir, writeSessionSummary, } from "./session-summary-writer.js";
+export { type ActiveMemoryTranscript, persistActiveMemoryTranscript } from "./transcript-store.js";
+export { discoverWikiFiles, type WikiFile, wikiDir } from "./wiki-loader.js";

package/dist/internal/memory/storage/index.js

@@ -0,0 +1,16 @@
+export { appendDiaryEntry, diaryPath, entryHash, readAllSqliteFacts, renderDiaryEntry } from '../../../chunk-WS5ULCL4.js';
+export { persistActiveMemoryTranscript } from '../../../chunk-OR6XIWLB.js';
+export { MEMORY_INDEX_MAX_BYTES, MEMORY_INDEX_MAX_LINES, appendFact, appendFactToMarkdown, asMemoryRoot, claudeProjectMemoryDir, collectMarkdownFiles, defaultIndexPath, discoverSessionFiles, discoverWikiFiles, indexBudgetWarning, lanceStoragePath, memoryIndexRoot, memoryMdPath, memoryReadRoots, notesDir, projectMemoryDir, readFacts, readFactsFromMarkdown, resolveMemoryRoot, sessionSummaryPath, sessionsDir, wikiDir, writeSessionSummary } from '../../../chunk-SADXXGWU.js';
+import '../../../chunk-KVNWIAO4.js';
+import '../../../chunk-FD2UT76F.js';
+import '../../../chunk-2XRAWOZZ.js';
+import '../../../chunk-EH6XD3FY.js';
+import '../../../chunk-UKMBRMGT.js';
+import '../../../chunk-JOFVLOFY.js';
+import '../../../chunk-6PWOWXMC.js';
+import '../../../chunk-Q5EWJPRY.js';
+import '../../../chunk-3JHIFQ4I.js';
+import '../../../chunk-ALUN2B4W.js';
+import '../../../chunk-CZJ6Q7CW.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/internal/memory/storage/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/internal/memory/storage/list-markdown.d.cts

@@ -0,0 +1 @@
+export {};

package/dist/internal/memory/storage/list-markdown.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/memory/storage/markdown-store.d.cts

@@ -0,0 +1,48 @@
+import { type MemoryConfig, type MemoryFact } from "../types.js";
+import { type MemoryLocationConfig, type MemoryRoot } from "./memory-root.js";
+/**
+ * Path to `MEMORY.md`, the index that points at the per-memory files — and, in stores written before
+ * #389, the flat `## Facts` list itself. Pure path computation; the file may not exist.
+ *
+ * Takes the RESOLVED ROOT, not a `cwd`. Every path helper here does, so a caller that has not asked
+ * {@link resolveMemoryRoot} where memory lives does not compile — see `memory-root.ts` for the
+ * defect that made that the requirement (#463).
+ */
+export declare function memoryMdPath(root: MemoryRoot): string;
+/**
+ * Path to `<memory root>/notes`, where per-topic notes and the consolidated notes a dreaming sweep
+ * writes live. Pure path computation — the directory may not exist.
+ */
+export declare function notesDir(root: MemoryRoot): string;
+/**
+ * Every memory in the store: the per-memory files, plus any legacy `## Facts` bullets still in
+ * `MEMORY.md`. Returns `[]` when the directory does not exist.
+ *
+ * Reading both is not transitional politeness. Those bullets are already on disk in consumers'
+ * repositories, and the store's own header invites editing them by hand — a converged writer that
+ * stopped reading them would delete what someone recorded, which is worse than the format it fixes.
+ */
+export declare function readFactsFromMarkdown(cwd: string, config?: MemoryLocationConfig): Promise<MemoryFact[]>;
+/**
+ * Write a fact as its own memory file and point the `MEMORY.md` index at it. Atomic + serialized.
+ *
+ * `modified` is stamped HERE and never read from `fact`: a timestamp a caller can set is a
+ * timestamp that can lie about when something was learned, and weighing recency is the point.
+ */
+export declare function appendFactToMarkdown(cwd: string, fact: MemoryFact, targetDir?: string): Promise<void>;
+/**
+ * Every memory in the store, honouring the `enabled` gate on {@link MemoryConfig}: when memory is
+ * disabled the call resolves to `[]` without touching disk. Configuration-aware entry point;
+ * {@link readFactsFromMarkdown} is the same read without the gate.
+ */
+export declare function readFacts(cwd: string, config: MemoryConfig): Promise<MemoryFact[]>;
+/**
+ * Record a fact, honouring the `enabled` gate on {@link MemoryConfig}: when memory is disabled the
+ * call resolves without touching disk. Configuration-aware entry point;
+ * {@link appendFactToMarkdown} is the same write without the gate.
+ *
+ * The destination comes from `memory.directory` and from nothing else. It used to come from
+ * `local.sessionDir` — the option that names the TRANSCRIPT home — so one option answered two
+ * questions and only this call site heard the second answer (#463).
+ */
+export declare function appendFact(cwd: string, config: MemoryConfig, fact: MemoryFact): Promise<void>;

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

@@ -0,0 +1,48 @@
+import { type MemoryConfig, type MemoryFact } from "../types.js";
+import { type MemoryLocationConfig, type MemoryRoot } from "./memory-root.js";
+/**
+ * Path to `MEMORY.md`, the index that points at the per-memory files — and, in stores written before
+ * #389, the flat `## Facts` list itself. Pure path computation; the file may not exist.
+ *
+ * Takes the RESOLVED ROOT, not a `cwd`. Every path helper here does, so a caller that has not asked
+ * {@link resolveMemoryRoot} where memory lives does not compile — see `memory-root.ts` for the
+ * defect that made that the requirement (#463).
+ */
+export declare function memoryMdPath(root: MemoryRoot): string;
+/**
+ * Path to `<memory root>/notes`, where per-topic notes and the consolidated notes a dreaming sweep
+ * writes live. Pure path computation — the directory may not exist.
+ */
+export declare function notesDir(root: MemoryRoot): string;
+/**
+ * Every memory in the store: the per-memory files, plus any legacy `## Facts` bullets still in
+ * `MEMORY.md`. Returns `[]` when the directory does not exist.
+ *
+ * Reading both is not transitional politeness. Those bullets are already on disk in consumers'
+ * repositories, and the store's own header invites editing them by hand — a converged writer that
+ * stopped reading them would delete what someone recorded, which is worse than the format it fixes.
+ */
+export declare function readFactsFromMarkdown(cwd: string, config?: MemoryLocationConfig): Promise<MemoryFact[]>;
+/**
+ * Write a fact as its own memory file and point the `MEMORY.md` index at it. Atomic + serialized.
+ *
+ * `modified` is stamped HERE and never read from `fact`: a timestamp a caller can set is a
+ * timestamp that can lie about when something was learned, and weighing recency is the point.
+ */
+export declare function appendFactToMarkdown(cwd: string, fact: MemoryFact, targetDir?: string): Promise<void>;
+/**
+ * Every memory in the store, honouring the `enabled` gate on {@link MemoryConfig}: when memory is
+ * disabled the call resolves to `[]` without touching disk. Configuration-aware entry point;
+ * {@link readFactsFromMarkdown} is the same read without the gate.
+ */
+export declare function readFacts(cwd: string, config: MemoryConfig): Promise<MemoryFact[]>;
+/**
+ * Record a fact, honouring the `enabled` gate on {@link MemoryConfig}: when memory is disabled the
+ * call resolves without touching disk. Configuration-aware entry point;
+ * {@link appendFactToMarkdown} is the same write without the gate.
+ *
+ * The destination comes from `memory.directory` and from nothing else. It used to come from
+ * `local.sessionDir` — the option that names the TRANSCRIPT home — so one option answered two
+ * questions and only this call site heard the second answer (#463).
+ */
+export declare function appendFact(cwd: string, config: MemoryConfig, fact: MemoryFact): Promise<void>;

package/dist/internal/memory/storage/memory-file.d.cts

@@ -0,0 +1,90 @@
+/**
+ * One memory as a file, in the shape the Claude Code CLI reads.
+ *
+ * `@theokit/sdk` already writes native Claude Code `.jsonl` sessions — the README's differentiator
+ * is "point `local.sessionDir` at `~/.claude` and the Claude Code CLI can `--continue` a session
+ * your agent wrote". Memory had no such convergence: a fact was a bullet under `## Facts` with its
+ * kind in an HTML comment (#389), which that CLI reads as prose. Pointing a memory directory at
+ * `~/.claude/projects/<project>/memory/` produced nothing it could open.
+ *
+ * The contract here was measured against a real store rather than inferred from documentation. Of
+ * nine files, all nine carry `name`, `description` and `metadata.type`; six also carry
+ * `node_type`, `originSessionId` and `modified`, which the runtime stamps on write. So the minimum
+ * a reader must accept is the first three — refusing the rest would refuse memories the CLI itself
+ * accepts.
+ *
+ * `originSessionId` is deliberately not written. It identifies the session that learned the fact,
+ * and the append path has no session in scope; inventing one would be worse than omitting a field
+ * the format already treats as optional.
+ *
+ * @internal
+ */
+import { type MemoryKind } from "../types.js";
+/** The fields one memory file carries. */
+export interface MemoryFileFields {
+    /** Slug, and the file's basename. */
+    readonly name: string;
+    /** One-line summary — what the index shows and what recall ranks. */
+    readonly description: string;
+    /** `metadata.type`, absent when the file does not declare one this contract admits. */
+    readonly kind?: MemoryKind;
+    /** `metadata.modified`, an ISO 8601 instant stamped by whoever wrote the file. */
+    readonly modified?: string;
+    /**
+     * How many times this exact text has been recorded — the corroboration count SOP-06-01 needs.
+     *
+     * One observation may be a coincidence, a mistake, or a plant. Requiring a second INDEPENDENT
+     * observation before an entry is treated as established is the cheapest defence against memory
+     * poisoning that exists, and a live run showed its absence is not theoretical: a single planted
+     * fact made the agent assert that the team's deploy convention was `--skip-tests`.
+     *
+     * Absent means one, so every file written before this field existed reads as uncorroborated
+     * rather than as trusted — the safe direction for a field that gates confidence.
+     */
+    readonly observations?: number;
+    /** The markdown after the frontmatter. */
+    readonly body: string;
+}
+/**
+ * A short, readable, filesystem-safe TOPIC name for `text` — not the text itself.
+ *
+ * WHY THIS IS NOT THE SENTENCE. The interop partner this store shares its format with names
+ * memories after their subject: measured over 688 real files, names average 30.6 characters and
+ * read like `prefere-explicacao-visual` or `zsh-sem-word-splitting` — two to five content words.
+ * This function used to lowercase the whole entry and cut it at 64 characters, which produced
+ * `the-deploy-passphrase-for-the-atlas-cluster-is-sirius-sod521`.
+ *
+ * That example is not hypothetical and it is the reason this changed. A filename is the most
+ * exposed part of an entry: it shows in directory listings, shell completion, tool logs and
+ * stack traces, none of which require opening the file. Naming a memory after its subject rather
+ * than its content keeps the payload out of the most-quoted field by construction, with no rule
+ * about secrets anywhere — a rule would have to recognise the secret, and pattern matching
+ * cannot recognise `sirius-sod521`.
+ *
+ * Readability remains the goal — a directory of `h-3f2a…` files is one nobody browses — but it is
+ * not the floor: anything failing the safe grammar falls back to {@link safeFilenameForId}, which
+ * is total.
+ */
+export declare function slugForFact(text: string): string;
+/**
+ * A short human-readable title for `text` — what the index shows in its link.
+ *
+ * The interop partner writes `- [Kernel batched AH JÁ EXISTE](slug.md) — <hook>`: a concept in
+ * the link and the detail after the dash. A caller that knows the concept SHOULD pass its own
+ * title; this is the fallback for the common path, where all the writer has is one sentence.
+ *
+ * It is deliberately mechanical. A derived title will not match an authored one, and pretending
+ * otherwise would be the mistake this codebase already refuses one field over — so the honest
+ * design is an explicit field with a derivation behind it, not a derivation dressed as authorship.
+ */
+export declare function titleForFact(text: string): string;
+/** Render one memory file. `description` is quoted so a colon in the text cannot break the block. */
+export declare function renderMemoryFile(fields: MemoryFileFields): string;
+/**
+ * Read one memory file, or `undefined` when the content is not one.
+ *
+ * `undefined` rather than a throw, and rather than a best-effort object: the directory holds
+ * hand-written notes and a `MEMORY.md` index alongside the memories, and turning any of those into
+ * a fact would put text into recall that nobody recorded as one.
+ */
+export declare function parseMemoryFile(raw: string): MemoryFileFields | undefined;