@theokit/sdk 4.62.0 → 4.63.0

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

@@ -3,6 +3,7 @@ import { type TelemetryHandle } from "../telemetry/tracer.js";
 import type { ActiveMemoryCache } from "./active-memory-cache.js";
 import type { ActiveMemoryQueryMode, ActiveMemoryResult, ActiveMemoryStatus } from "./active-memory-types.js";
 import type { MemoryIndex } from "./memory-index.js";
+import { type MemoryRoot } from "./storage/memory-root.js";
 export type { ActiveMemoryQueryMode, ActiveMemoryResult, ActiveMemoryStatus };
 export interface RunActiveMemoryArgs {
     userText: string;
@@ -18,7 +19,13 @@ export interface RunActiveMemoryArgs {
     cache?: ActiveMemoryCache;
     /** Workspace root for transcript persistence. */
     cwd?: string;
-    /** When true, write transcript JSON under .theokit/memory/transcripts/active-memory/. */
+    /**
+     * The memory root the caller already resolved. Falls back to the project store, which is right
+     * for a caller that has no `memory.directory` and wrong for one that does — so an agent passes
+     * its own (#463).
+     */
+    memoryRoot?: MemoryRoot;
+    /** When true, write transcript JSON under `<memory root>/transcripts/active-memory/`. */
     persistTranscripts?: boolean;
     /** Stable key the breaker + cache key by (default `default`). */
     agentKey?: string;

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

@@ -1,4 +1,41 @@
-export declare function diaryPath(cwd: string): string;
+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;
-export declare function appendDiaryEntry(cwd: string, entry: DiaryEntry): Promise<void>;
+/**
+ * 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/index-db.d.ts

@@ -1,3 +1,32 @@
+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 (used by sqlite-vec). */
+    loadExtension(path: string): void;
+}
 export interface OpenDbOptions {
     filePath: string;
     /**
@@ -7,4 +36,18 @@ export interface OpenDbOptions {
     recoverCorrupt?: boolean;
 }
 export declare function openMemoryDb(opts: OpenDbOptions): Promise<MemoryDb>;
-export declare function defaultIndexPath(cwd: string): string;
+/**
+ * `<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

@@ -1,4 +1,5 @@
 import type { EmbeddingRuntime } from "./embedding-adapter.js";
+import type { MemoryRoot } from "./storage/memory-root.js";
 export interface IndexStatus {
     backend: "fts-only" | "hybrid";
     filesIndexed: number;
@@ -18,6 +19,15 @@ export interface SearchOptions {
 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;

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

@@ -1 +1,20 @@
-export {};
+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

@@ -1,7 +1,7 @@
 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 cwd;
+    private readonly memoryRoot;
     private readonly db;
     private readonly embedding;
     private lastSyncMs;

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

@@ -1,4 +1,5 @@
 import type { EmbeddingRuntime } from "./embedding-adapter.js";
+import { type MemoryRoot } from "./storage/memory-root.js";
 export interface LanceFactRecord {
     id: string;
     text: string;
@@ -11,8 +12,10 @@ export interface LanceFactRecord {
 }
 export interface OpenLanceOptions {
     cwd: string;
+    /** The resolved memory root. Defaults to `<cwd>/.theokit/memory` (#463). */
+    memoryRoot?: MemoryRoot;
     embedding: EmbeddingRuntime;
-    /** Override storage location. Default: `<cwd>/.theokit/memory/lance/`. */
+    /** Override storage location. Default: `<memory root>/lance/`. */
     storagePath?: string;
 }
 export interface LanceSearchOptions {
@@ -30,3 +33,14 @@ export interface LanceSearchHit {
     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/migrate-sqlite-to-lance.d.ts

@@ -1,3 +1,23 @@
+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;
@@ -13,3 +33,26 @@ export interface MigrateResult {
     /** 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/storage/index.cjs

@@ -1,11 +1,14 @@
 'use strict';
 
-var chunk2UCFUSPW_cjs = require('../../../chunk-2UCFUSPW.cjs');
+var chunkIRCJ7EHV_cjs = require('../../../chunk-IRCJ7EHV.cjs');
+var chunkA4VHSE56_cjs = require('../../../chunk-A4VHSE56.cjs');
+var chunkEHJEZAOO_cjs = require('../../../chunk-EHJEZAOO.cjs');
 require('../../../chunk-KRD3GQAA.cjs');
 require('../../../chunk-MUUQ2WFJ.cjs');
 require('../../../chunk-R3UPQFKK.cjs');
 require('../../../chunk-VKJ7V7EB.cjs');
 require('../../../chunk-BUIK7GUA.cjs');
+require('../../../chunk-NXH4GPAQ.cjs');
 require('../../../chunk-ZF2LDKQQ.cjs');
 require('../../../chunk-I6TGFUCO.cjs');
 require('../../../chunk-K3FW2XZD.cjs');
@@ -14,41 +17,121 @@ require('../../../chunk-NUKRL3I6.cjs');
 
 
 
+Object.defineProperty(exports, "appendDiaryEntry", {
+  enumerable: true,
+  get: function () { return chunkIRCJ7EHV_cjs.appendDiaryEntry; }
+});
+Object.defineProperty(exports, "diaryPath", {
+  enumerable: true,
+  get: function () { return chunkIRCJ7EHV_cjs.diaryPath; }
+});
+Object.defineProperty(exports, "entryHash", {
+  enumerable: true,
+  get: function () { return chunkIRCJ7EHV_cjs.entryHash; }
+});
+Object.defineProperty(exports, "readAllSqliteFacts", {
+  enumerable: true,
+  get: function () { return chunkIRCJ7EHV_cjs.readAllSqliteFacts; }
+});
+Object.defineProperty(exports, "renderDiaryEntry", {
+  enumerable: true,
+  get: function () { return chunkIRCJ7EHV_cjs.renderDiaryEntry; }
+});
+Object.defineProperty(exports, "persistActiveMemoryTranscript", {
+  enumerable: true,
+  get: function () { return chunkA4VHSE56_cjs.persistActiveMemoryTranscript; }
+});
+Object.defineProperty(exports, "MEMORY_INDEX_MAX_BYTES", {
+  enumerable: true,
+  get: function () { return chunkEHJEZAOO_cjs.MEMORY_INDEX_MAX_BYTES; }
+});
+Object.defineProperty(exports, "MEMORY_INDEX_MAX_LINES", {
+  enumerable: true,
+  get: function () { return chunkEHJEZAOO_cjs.MEMORY_INDEX_MAX_LINES; }
+});
 Object.defineProperty(exports, "appendFact", {
   enumerable: true,
-  get: function () { return chunk2UCFUSPW_cjs.appendFact; }
+  get: function () { return chunkEHJEZAOO_cjs.appendFact; }
 });
 Object.defineProperty(exports, "appendFactToMarkdown", {
   enumerable: true,
-  get: function () { return chunk2UCFUSPW_cjs.appendFactToMarkdown; }
+  get: function () { return chunkEHJEZAOO_cjs.appendFactToMarkdown; }
+});
+Object.defineProperty(exports, "asMemoryRoot", {
+  enumerable: true,
+  get: function () { return chunkEHJEZAOO_cjs.asMemoryRoot; }
 });
 Object.defineProperty(exports, "claudeProjectMemoryDir", {
   enumerable: true,
-  get: function () { return chunk2UCFUSPW_cjs.claudeProjectMemoryDir; }
+  get: function () { return chunkEHJEZAOO_cjs.claudeProjectMemoryDir; }
+});
+Object.defineProperty(exports, "collectMarkdownFiles", {
+  enumerable: true,
+  get: function () { return chunkEHJEZAOO_cjs.collectMarkdownFiles; }
 });
-Object.defineProperty(exports, "memoryDir", {
+Object.defineProperty(exports, "defaultIndexPath", {
   enumerable: true,
-  get: function () { return chunk2UCFUSPW_cjs.memoryDir; }
+  get: function () { return chunkEHJEZAOO_cjs.defaultIndexPath; }
+});
+Object.defineProperty(exports, "discoverSessionFiles", {
+  enumerable: true,
+  get: function () { return chunkEHJEZAOO_cjs.discoverSessionFiles; }
+});
+Object.defineProperty(exports, "discoverWikiFiles", {
+  enumerable: true,
+  get: function () { return chunkEHJEZAOO_cjs.discoverWikiFiles; }
+});
+Object.defineProperty(exports, "indexBudgetWarning", {
+  enumerable: true,
+  get: function () { return chunkEHJEZAOO_cjs.indexBudgetWarning; }
+});
+Object.defineProperty(exports, "lanceStoragePath", {
+  enumerable: true,
+  get: function () { return chunkEHJEZAOO_cjs.lanceStoragePath; }
 });
 Object.defineProperty(exports, "memoryMdPath", {
   enumerable: true,
-  get: function () { return chunk2UCFUSPW_cjs.memoryMdPath; }
+  get: function () { return chunkEHJEZAOO_cjs.memoryMdPath; }
 });
-Object.defineProperty(exports, "memoryWriteDir", {
+Object.defineProperty(exports, "memoryReadRoots", {
   enumerable: true,
-  get: function () { return chunk2UCFUSPW_cjs.memoryWriteDir; }
+  get: function () { return chunkEHJEZAOO_cjs.memoryReadRoots; }
 });
 Object.defineProperty(exports, "notesDir", {
   enumerable: true,
-  get: function () { return chunk2UCFUSPW_cjs.notesDir; }
+  get: function () { return chunkEHJEZAOO_cjs.notesDir; }
+});
+Object.defineProperty(exports, "projectMemoryDir", {
+  enumerable: true,
+  get: function () { return chunkEHJEZAOO_cjs.projectMemoryDir; }
 });
 Object.defineProperty(exports, "readFacts", {
   enumerable: true,
-  get: function () { return chunk2UCFUSPW_cjs.readFacts; }
+  get: function () { return chunkEHJEZAOO_cjs.readFacts; }
 });
 Object.defineProperty(exports, "readFactsFromMarkdown", {
   enumerable: true,
-  get: function () { return chunk2UCFUSPW_cjs.readFactsFromMarkdown; }
+  get: function () { return chunkEHJEZAOO_cjs.readFactsFromMarkdown; }
+});
+Object.defineProperty(exports, "resolveMemoryRoot", {
+  enumerable: true,
+  get: function () { return chunkEHJEZAOO_cjs.resolveMemoryRoot; }
+});
+Object.defineProperty(exports, "sessionSummaryPath", {
+  enumerable: true,
+  get: function () { return chunkEHJEZAOO_cjs.sessionSummaryPath; }
+});
+Object.defineProperty(exports, "sessionsDir", {
+  enumerable: true,
+  get: function () { return chunkEHJEZAOO_cjs.sessionsDir; }
+});
+Object.defineProperty(exports, "wikiDir", {
+  enumerable: true,
+  get: function () { return chunkEHJEZAOO_cjs.wikiDir; }
+});
+Object.defineProperty(exports, "writeSessionSummary", {
+  enumerable: true,
+  get: function () { return chunkEHJEZAOO_cjs.writeSessionSummary; }
 });
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

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

@@ -15,4 +15,14 @@
  * 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 { appendFact, appendFactToMarkdown, claudeProjectMemoryDir, memoryDir, memoryMdPath, memoryWriteDir, notesDir, readFacts, readFactsFromMarkdown, } from "./markdown-store.js";
+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, 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

@@ -15,4 +15,14 @@
  * 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 { appendFact, appendFactToMarkdown, claudeProjectMemoryDir, memoryDir, memoryMdPath, memoryWriteDir, notesDir, readFacts, readFactsFromMarkdown, } from "./markdown-store.js";
+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, 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

@@ -1,9 +1,12 @@
-export { appendFact, appendFactToMarkdown, claudeProjectMemoryDir, memoryDir, memoryMdPath, memoryWriteDir, notesDir, readFacts, readFactsFromMarkdown } from '../../../chunk-WCLDJSMY.js';
+export { appendDiaryEntry, diaryPath, entryHash, readAllSqliteFacts, renderDiaryEntry } from '../../../chunk-R6TA2DRJ.js';
+export { persistActiveMemoryTranscript } from '../../../chunk-LW7G5DYW.js';
+export { MEMORY_INDEX_MAX_BYTES, MEMORY_INDEX_MAX_LINES, appendFact, appendFactToMarkdown, asMemoryRoot, claudeProjectMemoryDir, collectMarkdownFiles, defaultIndexPath, discoverSessionFiles, discoverWikiFiles, indexBudgetWarning, lanceStoragePath, memoryMdPath, memoryReadRoots, notesDir, projectMemoryDir, readFacts, readFactsFromMarkdown, resolveMemoryRoot, sessionSummaryPath, sessionsDir, wikiDir, writeSessionSummary } from '../../../chunk-C7QPML3L.js';
 import '../../../chunk-KVNWIAO4.js';
 import '../../../chunk-FD2UT76F.js';
 import '../../../chunk-QARJGQSA.js';
 import '../../../chunk-RIAM53CP.js';
 import '../../../chunk-FKMUFNQE.js';
+import '../../../chunk-AMFXSENK.js';
 import '../../../chunk-Q5EWJPRY.js';
 import '../../../chunk-VF7EWVDG.js';
 import '../../../chunk-IDCKSLYH.js';

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

@@ -1,49 +1,19 @@
 import { type MemoryConfig, type MemoryFact } from "../types.js";
-/**
- * The memory root for a workspace: `<cwd>/.theokit/memory`. Every other path here derives 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;
-/**
- * Where a NEW fact should be written.
- *
- * `.theokit/memory` by default, exactly as before. When the agent was given a `local.sessionDir`,
- * it becomes `<sessionDir>/projects/<encoded-cwd>/memory` — the same place the transcript for that
- * project goes, so a session and the memories recorded during it land beside each other.
- *
- * `local.sessionDir` is the switch because it is already the option this project documents for CLI
- * interop: point it at `~/.claude` and the CLI can `--continue` a session this agent wrote. Someone
- * who set it has said they share state with that CLI, and memory following is what the sentence
- * already implied. It needs no new option, and nothing moves for anyone who never set it.
- *
- * Safe because of the rule this pairs with — WRITE ONE, READ ALL. {@link readFactsFromMarkdown}
- * covers every location, so a consumer whose new facts move keeps every fact they already had. The
- * change relocates where the next one lands; it orphans nothing.
- */
-export declare function memoryWriteDir(cwd: string, sessionDir: string | undefined): string;
-/**
- * Where the Claude Code CLI keeps THIS project's memories.
- *
- * `<claudeHome>/projects/<encoded-cwd>/memory` — the same `encodeProjectDir` scheme the transcripts
- * already use, which is why no new encoding is invented here. `CLAUDE_CONFIG_DIR` names the home
- * when set (the CLI's own variable); `~/.claude` otherwise.
- *
- * Read, never written. Writing here by default would relocate every existing consumer's memories,
- * and an additive change must not move what is already on disk — so this is the direction that
- * costs nothing: a memory the CLI wrote becomes visible, and a memory the SDK wrote stays where the
- * SDK put it.
- */
-export declare function claudeProjectMemoryDir(cwd: string): string;
+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(cwd: string): string;
+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(cwd: string): string;
+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.
@@ -52,7 +22,7 @@ export declare function notesDir(cwd: string): string;
  * 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, sessionDir?: string): Promise<MemoryFact[]>;
+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.
  *
@@ -65,13 +35,14 @@ export declare function appendFactToMarkdown(cwd: string, fact: MemoryFact, targ
  * 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, memoryHome?: string): Promise<MemoryFact[]>;
+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.
  *
- * `memoryHome` is the agent's `local.sessionDir` when it has one — see {@link memoryWriteDir} for
- * which store that sends the fact to.
+ * 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, memoryHome?: string): Promise<void>;
+export declare function appendFact(cwd: string, config: MemoryConfig, fact: MemoryFact): Promise<void>;

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

@@ -1,49 +1,19 @@
 import { type MemoryConfig, type MemoryFact } from "../types.js";
-/**
- * The memory root for a workspace: `<cwd>/.theokit/memory`. Every other path here derives 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;
-/**
- * Where a NEW fact should be written.
- *
- * `.theokit/memory` by default, exactly as before. When the agent was given a `local.sessionDir`,
- * it becomes `<sessionDir>/projects/<encoded-cwd>/memory` — the same place the transcript for that
- * project goes, so a session and the memories recorded during it land beside each other.
- *
- * `local.sessionDir` is the switch because it is already the option this project documents for CLI
- * interop: point it at `~/.claude` and the CLI can `--continue` a session this agent wrote. Someone
- * who set it has said they share state with that CLI, and memory following is what the sentence
- * already implied. It needs no new option, and nothing moves for anyone who never set it.
- *
- * Safe because of the rule this pairs with — WRITE ONE, READ ALL. {@link readFactsFromMarkdown}
- * covers every location, so a consumer whose new facts move keeps every fact they already had. The
- * change relocates where the next one lands; it orphans nothing.
- */
-export declare function memoryWriteDir(cwd: string, sessionDir: string | undefined): string;
-/**
- * Where the Claude Code CLI keeps THIS project's memories.
- *
- * `<claudeHome>/projects/<encoded-cwd>/memory` — the same `encodeProjectDir` scheme the transcripts
- * already use, which is why no new encoding is invented here. `CLAUDE_CONFIG_DIR` names the home
- * when set (the CLI's own variable); `~/.claude` otherwise.
- *
- * Read, never written. Writing here by default would relocate every existing consumer's memories,
- * and an additive change must not move what is already on disk — so this is the direction that
- * costs nothing: a memory the CLI wrote becomes visible, and a memory the SDK wrote stays where the
- * SDK put it.
- */
-export declare function claudeProjectMemoryDir(cwd: string): string;
+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(cwd: string): string;
+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(cwd: string): string;
+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.
@@ -52,7 +22,7 @@ export declare function notesDir(cwd: string): string;
  * 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, sessionDir?: string): Promise<MemoryFact[]>;
+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.
  *
@@ -65,13 +35,14 @@ export declare function appendFactToMarkdown(cwd: string, fact: MemoryFact, targ
  * 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, memoryHome?: string): Promise<MemoryFact[]>;
+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.
  *
- * `memoryHome` is the agent's `local.sessionDir` when it has one — see {@link memoryWriteDir} for
- * which store that sends the fact to.
+ * 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, memoryHome?: string): Promise<void>;
+export declare function appendFact(cwd: string, config: MemoryConfig, fact: MemoryFact): Promise<void>;