@theokit/sdk 4.62.0 → 4.63.0

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

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

@@ -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[]>;

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

@@ -1,4 +1,5 @@
 import type { MemoryIndex } from "./memory-index.js";
+import type { MemoryRoot } from "./storage/memory-root.js";
 export interface MemoryTool extends MemoryToolJson {
     execute(input: Record<string, unknown>): Promise<string>;
 }
@@ -9,6 +10,12 @@ export interface MemorySearchToolOptions {
 }
 export declare function createMemorySearchTool(opts: MemorySearchToolOptions): MemoryTool;
 export interface MemoryGetToolOptions {
-    cwd: string;
+    /**
+     * The RESOLVED memory root the tool may read inside — not a cwd (#463).
+     *
+     * This guard used to derive its own root from `cwd` while `appendFact` wrote somewhere else, so
+     * a relocated memory was unreadable by the tool whose whole job is reading memory.
+     */
+    root: MemoryRoot;
 }
 export declare function createMemoryGetTool(opts: MemoryGetToolOptions): MemoryTool;

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

@@ -4,6 +4,11 @@ export interface MemoryConfig {
     userId?: string;
     scope?: "agent" | "user" | "team";
     storePath?: string;
+    /**
+     * Absolute path (or `~/`-prefixed) of the memory root. Defaults to `<cwd>/.theokit/memory`.
+     * See `storage/memory-root.ts` for why a relative value is refused rather than resolved.
+     */
+    directory?: string;
 }
 /**
  * What a fact IS, which is what decides whether it ages (#389).

package/dist/internal/persistence/index.cjs

@@ -2,7 +2,8 @@
 
 var chunkVTYY7XL5_cjs = require('../../chunk-VTYY7XL5.cjs');
 var chunkJ2UROOIG_cjs = require('../../chunk-J2UROOIG.cjs');
-var chunkSKXBJ2NU_cjs = require('../../chunk-SKXBJ2NU.cjs');
+var chunkA4RAL2ER_cjs = require('../../chunk-A4RAL2ER.cjs');
+var chunkNXH4GPAQ_cjs = require('../../chunk-NXH4GPAQ.cjs');
 var chunk2ADR2GSO_cjs = require('../../chunk-2ADR2GSO.cjs');
 var chunkZF2LDKQQ_cjs = require('../../chunk-ZF2LDKQQ.cjs');
 var chunkI6TGFUCO_cjs = require('../../chunk-I6TGFUCO.cjs');
@@ -53,25 +54,25 @@ Object.defineProperty(exports, "writeVersionedJson", {
   enumerable: true,
   get: function () { return chunkJ2UROOIG_cjs.writeVersionedJson; }
 });
-Object.defineProperty(exports, "applyWalWithFallback", {
+Object.defineProperty(exports, "containsCjk", {
   enumerable: true,
-  get: function () { return chunkSKXBJ2NU_cjs.applyWalWithFallback; }
+  get: function () { return chunkA4RAL2ER_cjs.containsCjk; }
 });
-Object.defineProperty(exports, "containsCjk", {
+Object.defineProperty(exports, "sanitizeFts5Query", {
   enumerable: true,
-  get: function () { return chunkSKXBJ2NU_cjs.containsCjk; }
+  get: function () { return chunkA4RAL2ER_cjs.sanitizeFts5Query; }
 });
-Object.defineProperty(exports, "isCorruptionError", {
+Object.defineProperty(exports, "applyWalWithFallback", {
   enumerable: true,
-  get: function () { return chunkSKXBJ2NU_cjs.isCorruptionError; }
+  get: function () { return chunkNXH4GPAQ_cjs.applyWalWithFallback; }
 });
-Object.defineProperty(exports, "openSqliteResilient", {
+Object.defineProperty(exports, "isCorruptionError", {
   enumerable: true,
-  get: function () { return chunkSKXBJ2NU_cjs.openSqliteResilient; }
+  get: function () { return chunkNXH4GPAQ_cjs.isCorruptionError; }
 });
-Object.defineProperty(exports, "sanitizeFts5Query", {
+Object.defineProperty(exports, "openSqliteResilient", {
   enumerable: true,
-  get: function () { return chunkSKXBJ2NU_cjs.sanitizeFts5Query; }
+  get: function () { return chunkNXH4GPAQ_cjs.openSqliteResilient; }
 });
 Object.defineProperty(exports, "JsonlParseError", {
   enumerable: true,

package/dist/internal/persistence/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/internal/persistence/exclusive-create.ts","../../../src/internal/persistence/sqlite-cas.ts"],"names":["open"],"mappings":";;;;;;;;;;;;;;AAwDA,eAAsB,eAAA,CACpB,IAAA,EACA,IAAA,EACA,OAAA,EACkB;AAClB,EAAA,MAAM,IAAA,GAAO,SAAS,IAAA,IAAQ,GAAA;AAC9B,EAAA,IAAI;AACF,IAAA,MAAM,MAAA,GAAS,MAAMA,aAAA,CAAK,IAAA,EAAM,MAAM,IAAI,CAAA;AAC1C,IAAA,IAAI;AACF,MAAA,MAAM,MAAA,CAAO,UAAU,IAAI,CAAA;AAC3B,MAAA,OAAO,IAAA;AAAA,IACT,CAAA,SAAE;AACA,MAAA,MAAM,OAAO,KAAA,EAAM;AAAA,IACrB;AAAA,EACF,SAAS,GAAA,EAAK;AACZ,IAAA,IAAK,GAAA,CAA8B,SAAS,QAAA,EAAU;AACpD,MAAA,OAAO,KAAA;AAAA,IACT;AACA,IAAA,MAAM,GAAA;AAAA,EACR;AACF;;;ACdO,SAAS,SAAA,CACd,EAAA,EACA,GAAA,EACA,MAAA,EACA,kBAA0B,CAAA,EACjB;AACT,EAAA,MAAM,IAAA,GAAO,EAAA,CAAG,OAAA,CAAQ,GAAG,CAAA;AAC3B,EAAA,MAAM,MAAA,GAAS,IAAA,CAAK,GAAA,CAAI,GAAI,MAAoB,CAAA;AAChD,EAAA,OAAO,OAAO,OAAA,KAAY,eAAA;AAC5B","file":"index.cjs","sourcesContent":["/**\n * O_EXCL exclusive file creation (ADR D82).\n *\n * `createExclusive(path, data, { mode })` creates a file in a single\n * syscall (`open(path, \"wx\", mode)`). Returns `true` if created, `false`\n * if it already existed (EEXIST swallowed — caller decides). All other\n * errors propagate.\n *\n * Default mode is 0o600 (owner-only) — EC-2 fix from edge-case review:\n * token files, lockfiles, and PID files MUST NOT default to world-\n * readable 0o644 under typical umask 022. Callers writing non-sensitive\n * files can pass `mode: 0o644` explicitly.\n *\n * NFS not honoring O_EXCL is documented (D61 — same stance as\n * `withFileLock`); the SDK target is ext4/APFS/NTFS.\n *\n * @internal\n */\n\nimport { open } from \"node:fs/promises\";\n\nexport interface CreateExclusiveOptions {\n  /** Unix mode for the new file (default 0o600 — owner-only). */\n  mode?: number;\n}\n\n/**\n * Create `path` holding `data`, but only if it does not exist yet. Returns `true` when this call\n * created it, `false` when it was already there.\n *\n * The check and the create are one `open(path, \"wx\")` syscall, so of N processes racing to create\n * the same path exactly one gets `true` — no window between testing and writing. The content is\n * written after the create, so the `false` branch tells you the file exists, not that another\n * writer has finished filling it.\n *\n * Only `EEXIST` becomes `false`. Every other error propagates: a missing parent directory is\n * `ENOENT`, an unwritable one `EACCES`. This never creates directories.\n *\n * The file is created with mode 0600 unless `options.mode` says otherwise, and the mode is\n * subject to the process umask. That default is deliberate — the callers are token files,\n * lockfiles and PID files, and 0644 under a typical umask would make them world-readable.\n *\n * **Choosing between this and the locks.** `createExclusive` claims a NAME once and is the right\n * tool for first-writer-wins: seeding a config, electing a single owner, writing a credential\n * exactly once. It cannot guard repeated updates, because a file that already exists always loses.\n * For read-modify-write on a path several writers touch, take a lock instead —\n * {@link withFileLock} across processes, `withCwdMutex` when the writers are all in this one. For\n * an in-place update guarded by a version column in SQLite, `casUpdate` is the equivalent\n * primitive.\n *\n * Atomicity is the filesystem's `O_EXCL`, which NFS does not reliably honor; the SDK targets\n * ext4, APFS and NTFS.\n *\n * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package\n * declares in `exports` but does NOT cover with its semver contract.\n */\nexport async function createExclusive(\n  path: string,\n  data: string | Uint8Array,\n  options?: CreateExclusiveOptions,\n): Promise<boolean> {\n  const mode = options?.mode ?? 0o600;\n  try {\n    const handle = await open(path, \"wx\", mode);\n    try {\n      await handle.writeFile(data);\n      return true;\n    } finally {\n      await handle.close();\n    }\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException).code === \"EEXIST\") {\n      return false;\n    }\n    throw err;\n  }\n}\n","/**\n * SQLite optimistic compare-and-swap (ADR D83).\n *\n * `casUpdate(db, sql, params, expectedChanges)` executes a prepared\n * UPDATE and returns true if `result.changes === expectedChanges`.\n * Caller provides the full SQL (including `WHERE version = ?` predicate);\n * helper does NOT generate SQL — DRY at the level of \"wrap the\n * convention\", not \"build queries\".\n *\n * Use case canonical (Hermes `kanban_db.py:1922-1934`):\n *\n *   const won = casUpdate(\n *     db,\n *     \"UPDATE registry SET status = ?, version = version + 1 WHERE id = ? AND version = ?\",\n *     [\"running\", \"agent-foo\", 3],\n *   );\n *   if (!won) { ... re-read and retry ... }\n *\n * Helper does NOT retry — caller responsible for backoff (avoids hidden\n * loops). Helper does NOT cache prepared statements — `better-sqlite3`\n * caches internally; SDK use is one-shot per mutation, not hot loops.\n *\n * NOTE — no internal-visibility tag in this block. `tsconfig.base.json` sets `stripInternal: true`,\n * and TypeScript scans EVERY leading comment range of the declaration that follows, including the\n * import right below this one. The tag that used to sit here deleted that import from the emitted\n * `.d.ts`, leaving the types it binds unresolvable for any consumer running type-aware lint\n * (usetheodev/theokit-sdk#283 records the same trap on a declaration).\n */\n\nimport type Database from \"better-sqlite3\";\n\ntype DatabaseInstance = InstanceType<typeof Database>;\n\n/**\n * Run an UPDATE and report whether it changed exactly the number of rows you expected — the\n * optimistic-concurrency equivalent of taking a lock.\n *\n * `sql` is yours, in full, including the guard that makes it a compare-and-swap: the\n * `WHERE ... AND version = ?` predicate and the `SET version = version + 1` that closes it. This\n * function generates nothing. It prepares the statement, runs it with `params`, and compares\n * `changes` against `expectedChanges` (default 1).\n *\n * `false` means the guard did not match — someone else moved the row first, or the id does not\n * exist. Those two are indistinguishable here; if you need to tell them apart, re-read the row.\n * A `false` return means NOTHING was written, so the caller owns the re-read-and-retry, with\n * whatever backoff it wants. There is no retry loop hidden in here, by design.\n *\n * SQL errors propagate — bad syntax, a closed database, a constraint violation, a busy writer.\n * Only the row-count mismatch is reported as `false`.\n *\n * Runs as a single implicit transaction, so no explicit BEGIN is needed for one statement. Wrap\n * the call yourself when the swap has to commit together with other writes.\n *\n * **Choosing between this and the locks.** `casUpdate` never blocks and never waits: the loser\n * finds out immediately and decides what to do. Prefer it when the contended state is already a\n * row with a version column. When the contended state is a FILE, there is no version column to\n * swap on — use `withFileLock` across processes, or `withCwdMutex` within one. When the goal is\n * to create something exactly once rather than update it, `createExclusive` is the primitive.\n *\n * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package\n * declares in `exports` but does NOT cover with its semver contract.\n */\nexport function casUpdate(\n  db: DatabaseInstance,\n  sql: string,\n  params: ReadonlyArray<unknown>,\n  expectedChanges: number = 1,\n): boolean {\n  const stmt = db.prepare(sql);\n  const result = stmt.run(...(params as unknown[]));\n  return result.changes === expectedChanges;\n}\n"]}
+{"version":3,"sources":["../../../src/internal/persistence/exclusive-create.ts","../../../src/internal/persistence/sqlite-cas.ts"],"names":["open"],"mappings":";;;;;;;;;;;;;;;AAwDA,eAAsB,eAAA,CACpB,IAAA,EACA,IAAA,EACA,OAAA,EACkB;AAClB,EAAA,MAAM,IAAA,GAAO,SAAS,IAAA,IAAQ,GAAA;AAC9B,EAAA,IAAI;AACF,IAAA,MAAM,MAAA,GAAS,MAAMA,aAAA,CAAK,IAAA,EAAM,MAAM,IAAI,CAAA;AAC1C,IAAA,IAAI;AACF,MAAA,MAAM,MAAA,CAAO,UAAU,IAAI,CAAA;AAC3B,MAAA,OAAO,IAAA;AAAA,IACT,CAAA,SAAE;AACA,MAAA,MAAM,OAAO,KAAA,EAAM;AAAA,IACrB;AAAA,EACF,SAAS,GAAA,EAAK;AACZ,IAAA,IAAK,GAAA,CAA8B,SAAS,QAAA,EAAU;AACpD,MAAA,OAAO,KAAA;AAAA,IACT;AACA,IAAA,MAAM,GAAA;AAAA,EACR;AACF;;;ACdO,SAAS,SAAA,CACd,EAAA,EACA,GAAA,EACA,MAAA,EACA,kBAA0B,CAAA,EACjB;AACT,EAAA,MAAM,IAAA,GAAO,EAAA,CAAG,OAAA,CAAQ,GAAG,CAAA;AAC3B,EAAA,MAAM,MAAA,GAAS,IAAA,CAAK,GAAA,CAAI,GAAI,MAAoB,CAAA;AAChD,EAAA,OAAO,OAAO,OAAA,KAAY,eAAA;AAC5B","file":"index.cjs","sourcesContent":["/**\n * O_EXCL exclusive file creation (ADR D82).\n *\n * `createExclusive(path, data, { mode })` creates a file in a single\n * syscall (`open(path, \"wx\", mode)`). Returns `true` if created, `false`\n * if it already existed (EEXIST swallowed — caller decides). All other\n * errors propagate.\n *\n * Default mode is 0o600 (owner-only) — EC-2 fix from edge-case review:\n * token files, lockfiles, and PID files MUST NOT default to world-\n * readable 0o644 under typical umask 022. Callers writing non-sensitive\n * files can pass `mode: 0o644` explicitly.\n *\n * NFS not honoring O_EXCL is documented (D61 — same stance as\n * `withFileLock`); the SDK target is ext4/APFS/NTFS.\n *\n * @internal\n */\n\nimport { open } from \"node:fs/promises\";\n\nexport interface CreateExclusiveOptions {\n  /** Unix mode for the new file (default 0o600 — owner-only). */\n  mode?: number;\n}\n\n/**\n * Create `path` holding `data`, but only if it does not exist yet. Returns `true` when this call\n * created it, `false` when it was already there.\n *\n * The check and the create are one `open(path, \"wx\")` syscall, so of N processes racing to create\n * the same path exactly one gets `true` — no window between testing and writing. The content is\n * written after the create, so the `false` branch tells you the file exists, not that another\n * writer has finished filling it.\n *\n * Only `EEXIST` becomes `false`. Every other error propagates: a missing parent directory is\n * `ENOENT`, an unwritable one `EACCES`. This never creates directories.\n *\n * The file is created with mode 0600 unless `options.mode` says otherwise, and the mode is\n * subject to the process umask. That default is deliberate — the callers are token files,\n * lockfiles and PID files, and 0644 under a typical umask would make them world-readable.\n *\n * **Choosing between this and the locks.** `createExclusive` claims a NAME once and is the right\n * tool for first-writer-wins: seeding a config, electing a single owner, writing a credential\n * exactly once. It cannot guard repeated updates, because a file that already exists always loses.\n * For read-modify-write on a path several writers touch, take a lock instead —\n * {@link withFileLock} across processes, `withCwdMutex` when the writers are all in this one. For\n * an in-place update guarded by a version column in SQLite, `casUpdate` is the equivalent\n * primitive.\n *\n * Atomicity is the filesystem's `O_EXCL`, which NFS does not reliably honor; the SDK targets\n * ext4, APFS and NTFS.\n *\n * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package\n * declares in `exports` but does NOT cover with its semver contract.\n */\nexport async function createExclusive(\n  path: string,\n  data: string | Uint8Array,\n  options?: CreateExclusiveOptions,\n): Promise<boolean> {\n  const mode = options?.mode ?? 0o600;\n  try {\n    const handle = await open(path, \"wx\", mode);\n    try {\n      await handle.writeFile(data);\n      return true;\n    } finally {\n      await handle.close();\n    }\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException).code === \"EEXIST\") {\n      return false;\n    }\n    throw err;\n  }\n}\n","/**\n * SQLite optimistic compare-and-swap (ADR D83).\n *\n * `casUpdate(db, sql, params, expectedChanges)` executes a prepared\n * UPDATE and returns true if `result.changes === expectedChanges`.\n * Caller provides the full SQL (including `WHERE version = ?` predicate);\n * helper does NOT generate SQL — DRY at the level of \"wrap the\n * convention\", not \"build queries\".\n *\n * Use case canonical (Hermes `kanban_db.py:1922-1934`):\n *\n *   const won = casUpdate(\n *     db,\n *     \"UPDATE registry SET status = ?, version = version + 1 WHERE id = ? AND version = ?\",\n *     [\"running\", \"agent-foo\", 3],\n *   );\n *   if (!won) { ... re-read and retry ... }\n *\n * Helper does NOT retry — caller responsible for backoff (avoids hidden\n * loops). Helper does NOT cache prepared statements — `better-sqlite3`\n * caches internally; SDK use is one-shot per mutation, not hot loops.\n *\n * NOTE — no internal-visibility tag in this block. `tsconfig.base.json` sets `stripInternal: true`,\n * and TypeScript scans EVERY leading comment range of the declaration that follows, including the\n * import right below this one. The tag that used to sit here deleted that import from the emitted\n * `.d.ts`, leaving the types it binds unresolvable for any consumer running type-aware lint\n * (usetheodev/theokit-sdk#283 records the same trap on a declaration).\n */\n\nimport type Database from \"better-sqlite3\";\n\ntype DatabaseInstance = InstanceType<typeof Database>;\n\n/**\n * Run an UPDATE and report whether it changed exactly the number of rows you expected — the\n * optimistic-concurrency equivalent of taking a lock.\n *\n * `sql` is yours, in full, including the guard that makes it a compare-and-swap: the\n * `WHERE ... AND version = ?` predicate and the `SET version = version + 1` that closes it. This\n * function generates nothing. It prepares the statement, runs it with `params`, and compares\n * `changes` against `expectedChanges` (default 1).\n *\n * `false` means the guard did not match — someone else moved the row first, or the id does not\n * exist. Those two are indistinguishable here; if you need to tell them apart, re-read the row.\n * A `false` return means NOTHING was written, so the caller owns the re-read-and-retry, with\n * whatever backoff it wants. There is no retry loop hidden in here, by design.\n *\n * SQL errors propagate — bad syntax, a closed database, a constraint violation, a busy writer.\n * Only the row-count mismatch is reported as `false`.\n *\n * Runs as a single implicit transaction, so no explicit BEGIN is needed for one statement. Wrap\n * the call yourself when the swap has to commit together with other writes.\n *\n * **Choosing between this and the locks.** `casUpdate` never blocks and never waits: the loser\n * finds out immediately and decides what to do. Prefer it when the contended state is already a\n * row with a version column. When the contended state is a FILE, there is no version column to\n * swap on — use `withFileLock` across processes, or `withCwdMutex` within one. When the goal is\n * to create something exactly once rather than update it, `createExclusive` is the primitive.\n *\n * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package\n * declares in `exports` but does NOT cover with its semver contract.\n */\nexport function casUpdate(\n  db: DatabaseInstance,\n  sql: string,\n  params: ReadonlyArray<unknown>,\n  expectedChanges: number = 1,\n): boolean {\n  const stmt = db.prepare(sql);\n  const result = stmt.run(...(params as unknown[]));\n  return result.changes === expectedChanges;\n}\n"]}

package/dist/internal/persistence/index.js

@@ -1,6 +1,7 @@
 export { PersistenceSchema } from '../../chunk-HY66GLM6.js';
 export { migrateSchema, readVersionedJson, writeVersionedJson } from '../../chunk-UCBJBJ27.js';
-export { applyWalWithFallback, containsCjk, isCorruptionError, openSqliteResilient, sanitizeFts5Query } from '../../chunk-CQ2TQ32Y.js';
+export { containsCjk, sanitizeFts5Query } from '../../chunk-WE22OXQA.js';
+export { applyWalWithFallback, isCorruptionError, openSqliteResilient } from '../../chunk-AMFXSENK.js';
 export { JsonlParseError, appendJsonl, loadJsonl, readJsonlIds, withFileLock } from '../../chunk-CV7XMBHP.js';
 export { withCwdMutex } from '../../chunk-Q5EWJPRY.js';
 export { atomicWriteJson, atomicWriteText, replaceFileAtomic } from '../../chunk-VF7EWVDG.js';