@theokit/sdk 4.62.0 → 4.63.1

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>;

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

@@ -0,0 +1,93 @@
+import type { MemoryConfig } from "../types.js";
+/**
+ * A path that {@link resolveMemoryRoot} produced — the only thing the subsystem's path helpers
+ * accept.
+ *
+ * The brand is what makes "every path derives from one resolution" a compiler rule rather than a
+ * convention. Both a `cwd` and a root are strings, so without it the helpers would go on accepting
+ * either, and the next one added would have the same even chance of taking the wrong one that
+ * produced #463 in the first place. It costs one cast, at the one place a caller legitimately has a
+ * directory that did not come from here.
+ *
+ * STRUCTURAL, not a `unique symbol`. A `unique symbol` brand is identity-based, and the d.ts
+ * bundler inlines the declaration into each package that re-exports it — so `@theokit/sdk-memory`
+ * ended up with a `MemoryRoot` its own compiler considered incompatible with the SDK's, on values
+ * that were the same string. A structural tag refuses a bare `string` exactly as well and survives
+ * the package boundary, which is where this type has to work.
+ */
+export type MemoryRoot = string & {
+    readonly __memoryRoot: "resolved";
+};
+/**
+ * Treat a directory as a memory root without resolving one.
+ *
+ * For the two honest cases: a test fixture, and a consumer opening an index against a store it
+ * located itself. Every other caller resolves.
+ */
+export declare function asMemoryRoot(dir: string): MemoryRoot;
+/** Only `directory` is read; the full config is accepted so callers pass what they already hold. */
+export type MemoryLocationConfig = Partial<MemoryConfig>;
+/**
+ * The project store: `<cwd>/.theokit/memory`. The default root, and always a READ root even when
+ * the write root moved — see {@link memoryReadRoots}.
+ */
+export declare function projectMemoryDir(cwd: string): MemoryRoot;
+/**
+ * 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. This is the half of the interop that decoupling the write MUST NOT cost: a
+ * memory the CLI recorded stays visible whatever `memory.directory` says.
+ */
+export declare function claudeProjectMemoryDir(cwd: string): MemoryRoot;
+/**
+ * The memory root for this agent: `memory.directory` when set, the project store otherwise.
+ *
+ * `directory` must be absolute or start with `~/`, which is the contract the interop partner
+ * documents for the same option. A relative path is REFUSED rather than resolved against the
+ * process cwd: the two plausible bases (workspace vs process) put memory in two different places,
+ * and picking one silently is how a store ends up split across both.
+ *
+ * @throws {ConfigurationError} `invalid_memory_directory` — the value is blank or relative.
+ */
+export declare function resolveMemoryRoot(cwd: string, config?: MemoryLocationConfig): MemoryRoot;
+/**
+ * The line limit the Claude Code CLI applies when it loads a `MEMORY.md`.
+ *
+ * Its number, not ours, and that is the point — see {@link indexBudgetWarning}.
+ */
+export declare const MEMORY_INDEX_MAX_LINES = 200;
+/**
+ * The byte limit the Claude Code CLI applies when it loads a `MEMORY.md`, whichever it reaches
+ * first. Also its number — see {@link indexBudgetWarning}.
+ */
+export declare const MEMORY_INDEX_MAX_BYTES: number;
+/**
+ * What to say about an index that the interop partner will truncate, or `undefined` when there is
+ * nothing true to say.
+ *
+ * **This is a statement about the PARTNER, not about us.** The CLI loads the first 200 lines / 25KB
+ * of `MEMORY.md` into every session and drops the rest in silence. We never load the index at all:
+ * the `<memory>` block is built from the per-memory FILES by `selectFactsForInjection`, ranked and
+ * capped, so our own recall does not degrade as the index grows. A warning that said "memory stops
+ * working" would be false here, and a warning that overstates is a warning somebody disables.
+ *
+ * It therefore speaks ONLY when the resolved root is the store the CLI reads. Anywhere else the
+ * index is ours, nobody truncates it, and the warning would be noise in every project that never
+ * opted into interop.
+ *
+ * Returns a string rather than emitting one: the caller decides what to do with it, and a pure
+ * function is testable without a filesystem or a captured stderr.
+ */
+export declare function indexBudgetWarning(index: string, root: string): string | undefined;
+/**
+ * Every directory a read must cover, deduplicated and in precedence order.
+ *
+ * WRITE ONE, READ ALL — this is what keeps a configured `directory` from orphaning anything. The
+ * configured root comes first, the project store second so memories recorded before the move stay
+ * readable, and the CLI's store last so interop survives the write being decoupled from it.
+ */
+export declare function memoryReadRoots(cwd: string, config?: MemoryLocationConfig): readonly MemoryRoot[];

package/dist/internal/memory/storage/memory-root.d.ts

@@ -0,0 +1,93 @@
+import type { MemoryConfig } from "../types.js";
+/**
+ * A path that {@link resolveMemoryRoot} produced — the only thing the subsystem's path helpers
+ * accept.
+ *
+ * The brand is what makes "every path derives from one resolution" a compiler rule rather than a
+ * convention. Both a `cwd` and a root are strings, so without it the helpers would go on accepting
+ * either, and the next one added would have the same even chance of taking the wrong one that
+ * produced #463 in the first place. It costs one cast, at the one place a caller legitimately has a
+ * directory that did not come from here.
+ *
+ * STRUCTURAL, not a `unique symbol`. A `unique symbol` brand is identity-based, and the d.ts
+ * bundler inlines the declaration into each package that re-exports it — so `@theokit/sdk-memory`
+ * ended up with a `MemoryRoot` its own compiler considered incompatible with the SDK's, on values
+ * that were the same string. A structural tag refuses a bare `string` exactly as well and survives
+ * the package boundary, which is where this type has to work.
+ */
+export type MemoryRoot = string & {
+    readonly __memoryRoot: "resolved";
+};
+/**
+ * Treat a directory as a memory root without resolving one.
+ *
+ * For the two honest cases: a test fixture, and a consumer opening an index against a store it
+ * located itself. Every other caller resolves.
+ */
+export declare function asMemoryRoot(dir: string): MemoryRoot;
+/** Only `directory` is read; the full config is accepted so callers pass what they already hold. */
+export type MemoryLocationConfig = Partial<MemoryConfig>;
+/**
+ * The project store: `<cwd>/.theokit/memory`. The default root, and always a READ root even when
+ * the write root moved — see {@link memoryReadRoots}.
+ */
+export declare function projectMemoryDir(cwd: string): MemoryRoot;
+/**
+ * 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. This is the half of the interop that decoupling the write MUST NOT cost: a
+ * memory the CLI recorded stays visible whatever `memory.directory` says.
+ */
+export declare function claudeProjectMemoryDir(cwd: string): MemoryRoot;
+/**
+ * The memory root for this agent: `memory.directory` when set, the project store otherwise.
+ *
+ * `directory` must be absolute or start with `~/`, which is the contract the interop partner
+ * documents for the same option. A relative path is REFUSED rather than resolved against the
+ * process cwd: the two plausible bases (workspace vs process) put memory in two different places,
+ * and picking one silently is how a store ends up split across both.
+ *
+ * @throws {ConfigurationError} `invalid_memory_directory` — the value is blank or relative.
+ */
+export declare function resolveMemoryRoot(cwd: string, config?: MemoryLocationConfig): MemoryRoot;
+/**
+ * The line limit the Claude Code CLI applies when it loads a `MEMORY.md`.
+ *
+ * Its number, not ours, and that is the point — see {@link indexBudgetWarning}.
+ */
+export declare const MEMORY_INDEX_MAX_LINES = 200;
+/**
+ * The byte limit the Claude Code CLI applies when it loads a `MEMORY.md`, whichever it reaches
+ * first. Also its number — see {@link indexBudgetWarning}.
+ */
+export declare const MEMORY_INDEX_MAX_BYTES: number;
+/**
+ * What to say about an index that the interop partner will truncate, or `undefined` when there is
+ * nothing true to say.
+ *
+ * **This is a statement about the PARTNER, not about us.** The CLI loads the first 200 lines / 25KB
+ * of `MEMORY.md` into every session and drops the rest in silence. We never load the index at all:
+ * the `<memory>` block is built from the per-memory FILES by `selectFactsForInjection`, ranked and
+ * capped, so our own recall does not degrade as the index grows. A warning that said "memory stops
+ * working" would be false here, and a warning that overstates is a warning somebody disables.
+ *
+ * It therefore speaks ONLY when the resolved root is the store the CLI reads. Anywhere else the
+ * index is ours, nobody truncates it, and the warning would be noise in every project that never
+ * opted into interop.
+ *
+ * Returns a string rather than emitting one: the caller decides what to do with it, and a pure
+ * function is testable without a filesystem or a captured stderr.
+ */
+export declare function indexBudgetWarning(index: string, root: string): string | undefined;
+/**
+ * Every directory a read must cover, deduplicated and in precedence order.
+ *
+ * WRITE ONE, READ ALL — this is what keeps a configured `directory` from orphaning anything. The
+ * configured root comes first, the project store second so memories recorded before the move stay
+ * readable, and the CLI's store last so interop survives the write being decoupled from it.
+ */
+export declare function memoryReadRoots(cwd: string, config?: MemoryLocationConfig): readonly MemoryRoot[];

package/dist/internal/memory/storage/session-loader.d.cts

@@ -1 +1,35 @@
-export declare function discoverSessionFiles(cwd: string): Promise<SessionFile[]>;
+import type { MemoryRoot } from "./memory-root.js";
+/**
+ * Session summary discovery (ADR D20).
+ *
+ * Mirrors `wiki-loader.ts:discoverWikiFiles`: scans
+ * `.theokit/memory/sessions/*.md` and returns `SessionFile` records —
+ * `{ absolutePath, relPath }`. IndexManager tags each chunk with
+ * `source="sessions"` so `memory_search({ corpus: "sessions" })` filters
+ * them in.
+ *
+ * B-140: this said "returns `MemoryFileEntry`-shaped records" and that was
+ * not true — `MemoryFileEntry` carried four fields (`path`, `relPath`,
+ * `mtime`, `hash`) against this function's two, and even the path field was
+ * named differently. Nothing consumed the interface, so it was removed and
+ * the sentence now names the type the function actually returns. A docblock
+ * asserting agreement between two shapes is worth no more than the agreement.
+ *
+ * Shared with `@theokit/sdk-memory` through the semver-exempt `internal/memory-store`
+ * sub-path, so it carries no internal-visibility tag. `stripInternal` matches that tag as TEXT
+ * anywhere in the block, so naming it here — even in backticks, even to say it is absent — deletes
+ * this symbol from the published declarations and forces the satellite back onto a copy. Measured:
+ * the first draft of this very note did exactly that. See #430 and #463.
+ */
+export interface SessionFile {
+    absolutePath: string;
+    relPath: string;
+}
+/**
+ * Every session summary under `<memory root>/sessions`, as `{ absolutePath, relPath }` records.
+ *
+ * Returns `[]` when the directory does not exist, so a workspace that has never finished a run is
+ * not an error. `IndexManager` tags what this returns with `source="sessions"`, which is what
+ * `memory_search({ corpus: "sessions" })` filters on.
+ */
+export declare function discoverSessionFiles(root: MemoryRoot): Promise<SessionFile[]>;

package/dist/internal/memory/storage/session-loader.d.ts

@@ -1 +1,35 @@
-export declare function discoverSessionFiles(cwd: string): Promise<SessionFile[]>;
+import type { MemoryRoot } from "./memory-root.js";
+/**
+ * Session summary discovery (ADR D20).
+ *
+ * Mirrors `wiki-loader.ts:discoverWikiFiles`: scans
+ * `.theokit/memory/sessions/*.md` and returns `SessionFile` records —
+ * `{ absolutePath, relPath }`. IndexManager tags each chunk with
+ * `source="sessions"` so `memory_search({ corpus: "sessions" })` filters
+ * them in.
+ *
+ * B-140: this said "returns `MemoryFileEntry`-shaped records" and that was
+ * not true — `MemoryFileEntry` carried four fields (`path`, `relPath`,
+ * `mtime`, `hash`) against this function's two, and even the path field was
+ * named differently. Nothing consumed the interface, so it was removed and
+ * the sentence now names the type the function actually returns. A docblock
+ * asserting agreement between two shapes is worth no more than the agreement.
+ *
+ * Shared with `@theokit/sdk-memory` through the semver-exempt `internal/memory-store`
+ * sub-path, so it carries no internal-visibility tag. `stripInternal` matches that tag as TEXT
+ * anywhere in the block, so naming it here — even in backticks, even to say it is absent — deletes
+ * this symbol from the published declarations and forces the satellite back onto a copy. Measured:
+ * the first draft of this very note did exactly that. See #430 and #463.
+ */
+export interface SessionFile {
+    absolutePath: string;
+    relPath: string;
+}
+/**
+ * Every session summary under `<memory root>/sessions`, as `{ absolutePath, relPath }` records.
+ *
+ * Returns `[]` when the directory does not exist, so a workspace that has never finished a run is
+ * not an error. `IndexManager` tags what this returns with `source="sessions"`, which is what
+ * `memory_search({ corpus: "sessions" })` filters on.
+ */
+export declare function discoverSessionFiles(root: MemoryRoot): Promise<SessionFile[]>;

package/dist/internal/memory/storage/session-summary-writer.d.cts

@@ -1,2 +1,50 @@
-export declare function sessionsDir(cwd: string): string;
-export declare function sessionSummaryPath(cwd: string, runId: string): string;
+import type { MemoryRoot } from "./memory-root.js";
+/**
+ * Per-run session summary writer (ADR D20).
+ *
+ * After every finished run, write a markdown summary to
+ * `.theokit/memory/sessions/<runId>.md`. IndexManager picks these up with
+ * `source="sessions"` so `memory_search({ corpus: "sessions" })` can recall
+ * past conversations.
+ *
+ * EC-9: only `status === "finished"` runs trigger a write. Cancelled/errored
+ * runs would otherwise pollute the recall corpus with partial transcripts.
+ *
+ * Shared with `@theokit/sdk-memory` through the semver-exempt `internal/memory-store`
+ * sub-path, so it carries no internal-visibility tag. `stripInternal` matches that tag as TEXT
+ * anywhere in the block, so naming it here — even in backticks, even to say it is absent — deletes
+ * this symbol from the published declarations and forces the satellite back onto a copy. Measured:
+ * the first draft of this very note did exactly that. See #430 and #463.
+ */
+export interface SessionSummaryInput {
+    /** The RESOLVED memory root, not a cwd — see `storage/memory-root.ts` (#463). */
+    memoryRoot: MemoryRoot;
+    runId: string;
+    agentId: string;
+    userText: string;
+    assistantText: string;
+    status: "finished" | "running" | "error" | "cancelled";
+    at: number;
+}
+/** `<memory root>/sessions`. Takes the RESOLVED ROOT — see `storage/memory-root.ts` (#463). */
+export declare function sessionsDir(root: MemoryRoot): string;
+/**
+ * The file one run's summary occupies: `<memory root>/sessions/<safe-id>.md`.
+ *
+ * The id passes through `safeFilenameForId`, so a UUID keeps its own name and anything else gets a
+ * deterministic `h-<16hex>` token. Deterministic matters more than readable here — a name that
+ * varied per call would orphan the summary it names.
+ */
+export declare function sessionSummaryPath(root: MemoryRoot, runId: string): string;
+/**
+ * Write a session summary file. EC-9: a non-finished status returns early
+ * without touching disk. Secrets in both user and assistant text are
+ * redacted via the shared `redactSecrets` pattern.
+ *
+ * Shared with `@theokit/sdk-memory` through the semver-exempt `internal/memory-store`
+ * sub-path, so it carries no internal-visibility tag. `stripInternal` matches that tag as TEXT
+ * anywhere in the block, so naming it here — even in backticks, even to say it is absent — deletes
+ * this symbol from the published declarations and forces the satellite back onto a copy. Measured:
+ * the first draft of this very note did exactly that. See #430 and #463.
+ */
+export declare function writeSessionSummary(input: SessionSummaryInput): Promise<void>;

package/dist/internal/memory/storage/session-summary-writer.d.ts

@@ -1,2 +1,50 @@
-export declare function sessionsDir(cwd: string): string;
-export declare function sessionSummaryPath(cwd: string, runId: string): string;
+import type { MemoryRoot } from "./memory-root.js";
+/**
+ * Per-run session summary writer (ADR D20).
+ *
+ * After every finished run, write a markdown summary to
+ * `.theokit/memory/sessions/<runId>.md`. IndexManager picks these up with
+ * `source="sessions"` so `memory_search({ corpus: "sessions" })` can recall
+ * past conversations.
+ *
+ * EC-9: only `status === "finished"` runs trigger a write. Cancelled/errored
+ * runs would otherwise pollute the recall corpus with partial transcripts.
+ *
+ * Shared with `@theokit/sdk-memory` through the semver-exempt `internal/memory-store`
+ * sub-path, so it carries no internal-visibility tag. `stripInternal` matches that tag as TEXT
+ * anywhere in the block, so naming it here — even in backticks, even to say it is absent — deletes
+ * this symbol from the published declarations and forces the satellite back onto a copy. Measured:
+ * the first draft of this very note did exactly that. See #430 and #463.
+ */
+export interface SessionSummaryInput {
+    /** The RESOLVED memory root, not a cwd — see `storage/memory-root.ts` (#463). */
+    memoryRoot: MemoryRoot;
+    runId: string;
+    agentId: string;
+    userText: string;
+    assistantText: string;
+    status: "finished" | "running" | "error" | "cancelled";
+    at: number;
+}
+/** `<memory root>/sessions`. Takes the RESOLVED ROOT — see `storage/memory-root.ts` (#463). */
+export declare function sessionsDir(root: MemoryRoot): string;
+/**
+ * The file one run's summary occupies: `<memory root>/sessions/<safe-id>.md`.
+ *
+ * The id passes through `safeFilenameForId`, so a UUID keeps its own name and anything else gets a
+ * deterministic `h-<16hex>` token. Deterministic matters more than readable here — a name that
+ * varied per call would orphan the summary it names.
+ */
+export declare function sessionSummaryPath(root: MemoryRoot, runId: string): string;
+/**
+ * Write a session summary file. EC-9: a non-finished status returns early
+ * without touching disk. Secrets in both user and assistant text are
+ * redacted via the shared `redactSecrets` pattern.
+ *
+ * Shared with `@theokit/sdk-memory` through the semver-exempt `internal/memory-store`
+ * sub-path, so it carries no internal-visibility tag. `stripInternal` matches that tag as TEXT
+ * anywhere in the block, so naming it here — even in backticks, even to say it is absent — deletes
+ * this symbol from the published declarations and forces the satellite back onto a copy. Measured:
+ * the first draft of this very note did exactly that. See #430 and #463.
+ */
+export declare function writeSessionSummary(input: SessionSummaryInput): Promise<void>;

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

@@ -1 +1,38 @@
-export declare function persistActiveMemoryTranscript(cwd: string, transcript: ActiveMemoryTranscript): Promise<void>;
+import type { MemoryRoot } from "./memory-root.js";
+/**
+ * Optional on-disk persistence for Active Memory recall transcripts (ADR D6).
+ *
+ * Writes one JSON file per run under
+ * `.theokit/memory/transcripts/active-memory/<runId>.json` when the agent
+ * passes `persistTranscripts: true`. Failures are swallowed with a stderr
+ * warning so transcript IO never crashes the agent run.
+ *
+ * Shared with `@theokit/sdk-memory` through the semver-exempt `internal/memory-store`
+ * sub-path, so it carries no internal-visibility tag. `stripInternal` matches that tag as TEXT
+ * anywhere in the block, so naming it here — even in backticks, even to say it is absent — deletes
+ * this symbol from the published declarations and forces the satellite back onto a copy. Measured:
+ * the first draft of this very note did exactly that. See #430 and #463.
+ */
+export interface ActiveMemoryTranscript {
+    runId: string;
+    startedAtMs: number;
+    userText: string;
+    queryMode: string;
+    status: string;
+    durationMs: number;
+    summary: string | undefined;
+    hits: ReadonlyArray<{
+        path: string;
+        startLine: number;
+        endLine: number;
+        score: number;
+        snippet: string;
+    }>;
+}
+/**
+ * Write one active-memory recall transcript under `<memory root>/transcripts/active-memory`.
+ *
+ * Never throws. Transcript IO is observability, and observability must not break the run it merely
+ * observes — a failure is reported through the diagnostics sink and swallowed.
+ */
+export declare function persistActiveMemoryTranscript(root: MemoryRoot, transcript: ActiveMemoryTranscript): Promise<void>;

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

@@ -1 +1,38 @@
-export declare function persistActiveMemoryTranscript(cwd: string, transcript: ActiveMemoryTranscript): Promise<void>;
+import type { MemoryRoot } from "./memory-root.js";
+/**
+ * Optional on-disk persistence for Active Memory recall transcripts (ADR D6).
+ *
+ * Writes one JSON file per run under
+ * `.theokit/memory/transcripts/active-memory/<runId>.json` when the agent
+ * passes `persistTranscripts: true`. Failures are swallowed with a stderr
+ * warning so transcript IO never crashes the agent run.
+ *
+ * Shared with `@theokit/sdk-memory` through the semver-exempt `internal/memory-store`
+ * sub-path, so it carries no internal-visibility tag. `stripInternal` matches that tag as TEXT
+ * anywhere in the block, so naming it here — even in backticks, even to say it is absent — deletes
+ * this symbol from the published declarations and forces the satellite back onto a copy. Measured:
+ * the first draft of this very note did exactly that. See #430 and #463.
+ */
+export interface ActiveMemoryTranscript {
+    runId: string;
+    startedAtMs: number;
+    userText: string;
+    queryMode: string;
+    status: string;
+    durationMs: number;
+    summary: string | undefined;
+    hits: ReadonlyArray<{
+        path: string;
+        startLine: number;
+        endLine: number;
+        score: number;
+        snippet: string;
+    }>;
+}
+/**
+ * Write one active-memory recall transcript under `<memory root>/transcripts/active-memory`.
+ *
+ * Never throws. Transcript IO is observability, and observability must not break the run it merely
+ * observes — a failure is reported through the diagnostics sink and swallowed.
+ */
+export declare function persistActiveMemoryTranscript(root: MemoryRoot, transcript: ActiveMemoryTranscript): Promise<void>;

package/dist/internal/memory/storage/wiki-loader.d.cts

@@ -1,2 +1,27 @@
-export declare function wikiDir(cwd: string): string;
-export declare function discoverWikiFiles(cwd: string): Promise<WikiFile[]>;
+import type { MemoryRoot } from "./memory-root.js";
+/**
+ * Wiki supplement discovery (ADR Phase 10 of memory-system-peer-project-parity).
+ *
+ * Wiki files live under `.theokit/memory/wiki/*.md`. They are READ-ONLY —
+ * the SDK never writes here. Each indexed chunk carries `source="wiki"` so
+ * `memory_search { corpus: "wiki" }` and `corpus: "all"` can scope hits.
+ *
+ * Shared with `@theokit/sdk-memory` through the semver-exempt `internal/memory-store`
+ * sub-path, so it carries no internal-visibility tag. `stripInternal` matches that tag as TEXT
+ * anywhere in the block, so naming it here — even in backticks, even to say it is absent — deletes
+ * this symbol from the published declarations and forces the satellite back onto a copy. Measured:
+ * the first draft of this very note did exactly that. See #430 and #463.
+ */
+export interface WikiFile {
+    absolutePath: string;
+    relPath: string;
+}
+/** `<memory root>/wiki`. Takes the RESOLVED ROOT — see `storage/memory-root.ts` (#463). */
+export declare function wikiDir(root: MemoryRoot): string;
+/**
+ * Every wiki supplement under `<memory root>/wiki`, as `{ absolutePath, relPath }` records.
+ *
+ * Returns `[]` when the directory does not exist. These are read-only supplements the indexer tags
+ * with `source="wiki"`, so `memory_search({ corpus: "wiki" })` can scope to them.
+ */
+export declare function discoverWikiFiles(root: MemoryRoot): Promise<WikiFile[]>;