@theokit/sdk 4.62.0 → 4.63.1

package/dist/types/agent.d.ts

@@ -270,6 +270,17 @@ export interface MemorySettings {
     userId?: string;
     scope?: "agent" | "user" | "team";
     storePath?: string;
+    /**
+     * Where this agent's memory lives. Default `<cwd>/.theokit/memory`.
+     *
+     * Must be an absolute path or start with `~/` — a relative value is refused rather than
+     * resolved, because the two plausible bases put the store in two different places.
+     *
+     * Point it at `~/.claude/projects/<encoded-cwd>/memory` to WRITE where the Claude Code CLI
+     * reads. That store is READ unconditionally either way, so setting this is only needed to
+     * share the writes.
+     */
+    directory?: string;
     /**
      * Whether the SDK auto-injects recalled facts as a `<memory>` block in the
      * LLM system prompt. Default `true`.

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

@@ -66,6 +66,14 @@ export interface RecordSessionSummaryArgs {
      * compute the markdown file path.
      */
     readonly cwd: string;
+    /**
+     * The memory root the kernel resolved for this agent, from `memory.directory` or the default.
+     *
+     * Supplied by the kernel, never constructed by an implementor — which is why it is required
+     * rather than optional. An implementation that recomputed it from `cwd` would write the summary
+     * into a different directory than the one the rest of the subsystem uses (#463).
+     */
+    readonly memoryRoot: import("../internal/memory/storage/memory-root.js").MemoryRoot;
     /** Run id used as the filename key. */
     readonly runId: string;
     /** Agent identity for scope (foldering). */

package/dist/workflow.cjs

@@ -1,101 +1,101 @@
 'use strict';
 
-var chunk6SBW4QR2_cjs = require('./chunk-6SBW4QR2.cjs');
-var chunkXWL6O3SW_cjs = require('./chunk-XWL6O3SW.cjs');
+var chunkYML4ME27_cjs = require('./chunk-YML4ME27.cjs');
+var chunkWNO3C3N2_cjs = require('./chunk-WNO3C3N2.cjs');
 require('./chunk-VTYY7XL5.cjs');
 require('./chunk-WJVHMTKB.cjs');
-require('./chunk-R3UPQFKK.cjs');
+require('./chunk-V2BOS4WF.cjs');
 require('./chunk-VKJ7V7EB.cjs');
-require('./chunk-I6TGFUCO.cjs');
-require('./chunk-K3FW2XZD.cjs');
-require('./chunk-JTB5Q42C.cjs');
-require('./chunk-NUKRL3I6.cjs');
+require('./chunk-UALX2J2Q.cjs');
+require('./chunk-4ZHTIJNE.cjs');
+require('./chunk-XL7Q7HB2.cjs');
+require('./chunk-EG4QM7ZJ.cjs');
 
 
 
 Object.defineProperty(exports, "Workflow", {
   enumerable: true,
-  get: function () { return chunk6SBW4QR2_cjs.Workflow; }
+  get: function () { return chunkYML4ME27_cjs.Workflow; }
 });
 Object.defineProperty(exports, "WorkflowBuilder", {
   enumerable: true,
-  get: function () { return chunk6SBW4QR2_cjs.WorkflowBuilder; }
+  get: function () { return chunkYML4ME27_cjs.WorkflowBuilder; }
 });
 Object.defineProperty(exports, "WorkflowToolError", {
   enumerable: true,
-  get: function () { return chunk6SBW4QR2_cjs.WorkflowToolError; }
+  get: function () { return chunkYML4ME27_cjs.WorkflowToolError; }
 });
 Object.defineProperty(exports, "agentStep", {
   enumerable: true,
-  get: function () { return chunk6SBW4QR2_cjs.agentStep; }
+  get: function () { return chunkYML4ME27_cjs.agentStep; }
 });
 Object.defineProperty(exports, "cloneWorkflow", {
   enumerable: true,
-  get: function () { return chunk6SBW4QR2_cjs.cloneWorkflow; }
+  get: function () { return chunkYML4ME27_cjs.cloneWorkflow; }
 });
 Object.defineProperty(exports, "fn", {
   enumerable: true,
-  get: function () { return chunk6SBW4QR2_cjs.fn; }
+  get: function () { return chunkYML4ME27_cjs.fn; }
 });
 Object.defineProperty(exports, "workflowAsTool", {
   enumerable: true,
-  get: function () { return chunk6SBW4QR2_cjs.workflowAsTool; }
+  get: function () { return chunkYML4ME27_cjs.workflowAsTool; }
 });
 Object.defineProperty(exports, "workflowStep", {
   enumerable: true,
-  get: function () { return chunk6SBW4QR2_cjs.workflowStep; }
+  get: function () { return chunkYML4ME27_cjs.workflowStep; }
 });
 Object.defineProperty(exports, "WorkflowAlreadyRunningError", {
   enumerable: true,
-  get: function () { return chunkXWL6O3SW_cjs.WorkflowAlreadyRunningError; }
+  get: function () { return chunkWNO3C3N2_cjs.WorkflowAlreadyRunningError; }
 });
 Object.defineProperty(exports, "WorkflowCompensateNotImplementedError", {
   enumerable: true,
-  get: function () { return chunkXWL6O3SW_cjs.WorkflowCompensateNotImplementedError; }
+  get: function () { return chunkWNO3C3N2_cjs.WorkflowCompensateNotImplementedError; }
 });
 Object.defineProperty(exports, "WorkflowDuplicateStepIdError", {
   enumerable: true,
-  get: function () { return chunkXWL6O3SW_cjs.WorkflowDuplicateStepIdError; }
+  get: function () { return chunkWNO3C3N2_cjs.WorkflowDuplicateStepIdError; }
 });
 Object.defineProperty(exports, "WorkflowInputError", {
   enumerable: true,
-  get: function () { return chunkXWL6O3SW_cjs.WorkflowInputError; }
+  get: function () { return chunkWNO3C3N2_cjs.WorkflowInputError; }
 });
 Object.defineProperty(exports, "WorkflowMaxIterationsExceededError", {
   enumerable: true,
-  get: function () { return chunkXWL6O3SW_cjs.WorkflowMaxIterationsExceededError; }
+  get: function () { return chunkWNO3C3N2_cjs.WorkflowMaxIterationsExceededError; }
 });
 Object.defineProperty(exports, "WorkflowNestedError", {
   enumerable: true,
-  get: function () { return chunkXWL6O3SW_cjs.WorkflowNestedError; }
+  get: function () { return chunkWNO3C3N2_cjs.WorkflowNestedError; }
 });
 Object.defineProperty(exports, "WorkflowNotSerializableError", {
   enumerable: true,
-  get: function () { return chunkXWL6O3SW_cjs.WorkflowNotSerializableError; }
+  get: function () { return chunkWNO3C3N2_cjs.WorkflowNotSerializableError; }
 });
 Object.defineProperty(exports, "WorkflowOutputError", {
   enumerable: true,
-  get: function () { return chunkXWL6O3SW_cjs.WorkflowOutputError; }
+  get: function () { return chunkWNO3C3N2_cjs.WorkflowOutputError; }
 });
 Object.defineProperty(exports, "WorkflowParallelError", {
   enumerable: true,
-  get: function () { return chunkXWL6O3SW_cjs.WorkflowParallelError; }
+  get: function () { return chunkWNO3C3N2_cjs.WorkflowParallelError; }
 });
 Object.defineProperty(exports, "WorkflowResumeStepNotFoundError", {
   enumerable: true,
-  get: function () { return chunkXWL6O3SW_cjs.WorkflowResumeStepNotFoundError; }
+  get: function () { return chunkWNO3C3N2_cjs.WorkflowResumeStepNotFoundError; }
 });
 Object.defineProperty(exports, "WorkflowSnapshotNotFoundError", {
   enumerable: true,
-  get: function () { return chunkXWL6O3SW_cjs.WorkflowSnapshotNotFoundError; }
+  get: function () { return chunkWNO3C3N2_cjs.WorkflowSnapshotNotFoundError; }
 });
 Object.defineProperty(exports, "WorkflowStateError", {
   enumerable: true,
-  get: function () { return chunkXWL6O3SW_cjs.WorkflowStateError; }
+  get: function () { return chunkWNO3C3N2_cjs.WorkflowStateError; }
 });
 Object.defineProperty(exports, "__resetSnapshotStoresForTests", {
   enumerable: true,
-  get: function () { return chunkXWL6O3SW_cjs.__resetSnapshotStoresForTests; }
+  get: function () { return chunkWNO3C3N2_cjs.__resetSnapshotStoresForTests; }
 });
 //# sourceMappingURL=workflow.cjs.map
 //# sourceMappingURL=workflow.cjs.map

package/dist/workflow.js

@@ -1,12 +1,12 @@
-export { Workflow, WorkflowBuilder, WorkflowToolError, agentStep, cloneWorkflow, fn, workflowAsTool, workflowStep } from './chunk-FUL2I7G5.js';
-export { WorkflowAlreadyRunningError, WorkflowCompensateNotImplementedError, WorkflowDuplicateStepIdError, WorkflowInputError, WorkflowMaxIterationsExceededError, WorkflowNestedError, WorkflowNotSerializableError, WorkflowOutputError, WorkflowParallelError, WorkflowResumeStepNotFoundError, WorkflowSnapshotNotFoundError, WorkflowStateError, __resetSnapshotStoresForTests } from './chunk-AQLGBKNT.js';
+export { Workflow, WorkflowBuilder, WorkflowToolError, agentStep, cloneWorkflow, fn, workflowAsTool, workflowStep } from './chunk-OSEG74VJ.js';
+export { WorkflowAlreadyRunningError, WorkflowCompensateNotImplementedError, WorkflowDuplicateStepIdError, WorkflowInputError, WorkflowMaxIterationsExceededError, WorkflowNestedError, WorkflowNotSerializableError, WorkflowOutputError, WorkflowParallelError, WorkflowResumeStepNotFoundError, WorkflowSnapshotNotFoundError, WorkflowStateError, __resetSnapshotStoresForTests } from './chunk-BZRFXJHA.js';
 import './chunk-HY66GLM6.js';
 import './chunk-4VPXM6UU.js';
-import './chunk-QARJGQSA.js';
+import './chunk-HS7AVXTF.js';
 import './chunk-RIAM53CP.js';
-import './chunk-VF7EWVDG.js';
-import './chunk-IDCKSLYH.js';
-import './chunk-T7XEKOVW.js';
-import './chunk-T7O6K6PX.js';
+import './chunk-2GUYQR5P.js';
+import './chunk-ZZMZWBR6.js';
+import './chunk-D4CUGAKZ.js';
+import './chunk-XEQ3TM66.js';
 //# sourceMappingURL=workflow.js.map
 //# sourceMappingURL=workflow.js.map

package/docs/error-codes.md

@@ -6,7 +6,7 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 
 **Transport codes vs the rest.** `ErrorCode` in `errors.ts` is the small canonical union a provider failure maps onto — the codes marked *transport* below. Everything else is raised by a specific subsystem at a specific place, and a `catch` that only handles the union will meet them anyway.
 
-205 distinct code(s).
+206 distinct code(s).
 
 | Code | Kind | Raised by | Sites |
 |---|---|---|---|
@@ -53,7 +53,7 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `cron_no_target` | domain | ConfigurationError | `packages/sdk/src/cron.ts:220` +1 |
 | `cron_workflow_message` | domain | ConfigurationError | `packages/sdk/src/cron.ts:226` |
 | `duplicate_tool_name` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:201` |
-| `embedding_dimension_mismatch` | domain | ConfigurationError | `packages/sdk/src/internal/memory/lance-index.ts:142` +1 |
+| `embedding_dimension_mismatch` | domain | ConfigurationError | `packages/sdk/src/internal/memory/lance-index.ts:146` +1 |
 | `embedding_invalid_response` | domain | NetworkError | `packages/sdk/src/internal/memory/adapters/openai-compatible.ts:370` |
 | `embedding_missing_api_key` | domain | AuthenticationError | `packages/sdk/src/internal/memory/adapters/openai-compatible.ts:129` |
 | `embedding_unknown_model` | domain | ConfigurationError | `packages/sdk/src/internal/memory/adapters/openai-compatible.ts:141` |
@@ -88,7 +88,8 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `invalid_input` | domain | MemoryAdapterError | `packages/memory-honcho/src/adapter.ts:98` +9 |
 | `invalid_max_iterations` | domain | ConfigurationError | `packages/sdk/src/internal/local-agent/real-local-run.ts:215` |
 | `invalid_memory_backend` | domain | ConfigurationError | `packages/sdk/src/internal/memory/index-manager-dispatch.ts:24` +1 |
-| `invalid_memory_kind` | domain | ConfigurationError | `packages/sdk/src/internal/memory/storage/markdown-store.ts:233` |
+| `invalid_memory_directory` | domain | ConfigurationError | `packages/sdk/src/internal/memory/storage/memory-root.ts:105` |
+| `invalid_memory_kind` | domain | ConfigurationError | `packages/sdk/src/internal/memory/storage/markdown-store.ts:206` |
 | `invalid_model_selection` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/model-selection.ts:21` |
 | `invalid_request` | transport | — | `packages/sdk/src/internal/error-mappers/vertex.ts:52` +1 |
 | `invalid_retry_config` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/retry/with-retry.ts:67` |
@@ -97,7 +98,7 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `invalid_timezone` | domain | ConfigurationError | `packages/sdk/src/internal/cron/validate.ts:134` |
 | `iteration_limit_reached` | domain | — | `packages/sdk/src/internal/agent-loop/loop.ts:149` |
 | `judge_credential` | domain | — | `packages/sdk/src/internal/judge/judge-call.ts:72` +1 |
-| `lance_backend_unavailable` | domain | ConfigurationError | `packages/sdk/src/internal/memory/lance-index.ts:102` +3 |
+| `lance_backend_unavailable` | domain | ConfigurationError | `packages/sdk/src/internal/memory/lance-index.ts:105` +3 |
 | `lance_requires_embedding` | domain | ConfigurationError | `packages/sdk/src/internal/memory/index-manager-dispatch.ts:39` +1 |
 | `live_session_protected` | domain | — | `packages/sdk/src/internal/persistence/transcript-ops.ts:39` +1 |
 | `local_provider_http_error` | domain | ConfigurationError | `packages/sdk/src/internal/catalog/local-models.ts:61` |
@@ -112,11 +113,11 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `mcp_not_init` | domain | ConfigurationError | `packages/sdk/src/internal/mcp/client.ts:251` +2 |
 | `mcp_timeout` | domain | NetworkError | `packages/sdk/src/internal/mcp/client.ts:71` |
 | `memory_context_missing_user_id` | domain | ConfigurationError | `packages/sdk/src/internal/local-agent/local-agent-memory-direct.ts:128` |
-| `memory_path_escapes_root` | domain | ConfigurationError | `packages/sdk/src/internal/memory/tools.ts:109` +1 |
+| `memory_path_escapes_root` | domain | ConfigurationError | `packages/sdk/src/internal/memory/tools.ts:115` +1 |
 | `memory_path_traversal` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:280` |
-| `memory_threat_rejected` | domain | ConfigurationError | `packages/sdk/src/internal/memory/storage/markdown-store.ts:250` |
-| `memory_tool_bad_args` | domain | ConfigurationError | `packages/sdk/src/internal/memory/tools.ts:132` +1 |
-| `migration_destination_exists` | domain | ConfigurationError | `packages/sdk/src/internal/memory/migrate-sqlite-to-lance.ts:114` +1 |
+| `memory_threat_rejected` | domain | ConfigurationError | `packages/sdk/src/internal/memory/storage/markdown-store.ts:223` |
+| `memory_tool_bad_args` | domain | ConfigurationError | `packages/sdk/src/internal/memory/tools.ts:138` +1 |
+| `migration_destination_exists` | domain | ConfigurationError | `packages/sdk/src/internal/memory/migrate-sqlite-to-lance.ts:127` +1 |
 | `missing_api_key` | domain | AuthenticationError, ConfigurationError | `packages/sdk/src/agent-helpers.ts:217` +2 |
 | `missing_frontmatter` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/skill-frontmatter.ts:66` |
 | `missing_model` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:35` |
@@ -167,7 +168,7 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `schema_invalid` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/skill-frontmatter.ts:77` +3 |
 | `server_error` | transport | buildErrorMetadata | `packages/sdk/src/internal/error-mappers/ollama.ts:92` +2 |
 | `session_busy` | domain | — | `packages/sdk/src/internal/persistence/session-writer.ts:56` +1 |
-| `sql_injection_blocked` | domain | ConfigurationError | `packages/sdk/src/internal/memory/lance-index.ts:252` +3 |
+| `sql_injection_blocked` | domain | ConfigurationError | `packages/sdk/src/internal/memory/lance-index.ts:256` +3 |
 | `sqlite_driver_unavailable` | domain | ConfigurationError | `packages/sdk/src/internal/persistence/sqlite-open.ts:192` |
 | `sqlite_vec_unavailable` | domain | ConfigurationError | `packages/sdk/src/internal/memory/sqlite-vec-loader.ts:23` +1 |
 | `squad_process_unsupported` | domain | ConfigurationError | `packages/sdk/src/squad.ts:117` |

package/docs/harness-capability-map.md

@@ -4,7 +4,7 @@ Every public symbol the TheoKit workspace publishes, and the exact specifier to
 
 A symbol listed under two specifiers is reachable from both, but that does NOT make the two interchangeable: a class emitted separately into a subpath entry is a distinct nominal type from the one in the root bundle, so passing one where the other is expected fails on a private field. When a symbol appears twice, import it and everything it is passed to from the SAME specifier.
 
-1137 export(s) across 46 entry point(s).
+1177 export(s) across 46 entry point(s).
 
 ## `@theokit/acp`
 
@@ -526,9 +526,10 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `ActiveMemoryResult` | interface | Result of one recall attempt.  |
 | `ActiveMemoryStatus` | type | Outcome of one recall attempt.  |
 | `ActiveMemoryTranscript` | interface | Optional on-disk persistence for Active Memory recall transcripts (ADR D6).  |
-| `appendDiaryEntry` | function | Append one entry to the dream diary, creating the file with a `# Dream Diary` header when it does not exist yet.  |
+| `appendDiaryEntry` | function | Append one sweep's entry to `<memory root>/dream-diary.md`, creating the file with its header when this is the first sweep.  |
 | `appendFact` | function | Record a fact, honouring the `enabled` gate on {@link MemoryConfig } : when memory is disabled the call resolves without touching disk.  |
 | `appendFactToMarkdown` | function | Write a fact as its own memory file and point the `MEMORY.md` index at it.  |
+| `asMemoryRoot` | function | Treat a directory as a memory root without resolving one.  |
 | `assertValidBackend` | function | EC-1: runtime guard for `opts.backend`.  |
 | `azureOpenAiMemoryEmbeddingProviderAdapter` | const | Azure OpenAI embeddings.  |
 | `buildErrorMetadata` | function | Build an `ErrorMetadata` object with all optional fields included conditionally (no `undefined` keys in the output). |
@@ -542,6 +543,7 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `Cluster` | interface | A group of facts the REM phase judged related.  |
 | `ClusterResult` | interface | What {@link remPhase } produced.  |
 | `cohereMemoryEmbeddingProviderAdapter` | const | Cohere embeddings.  |
+| `collectMarkdownFiles` | function | 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.  |
 | `CreateAdapterOptions` | interface | Per-call overrides handed to {@link MemoryEmbeddingProviderAdapter.create } .  |
 | `createCategorizedMemory` | function | Create a typed categorized memory store over the closed `categories` taxonomy.  |
 | `CreateCategorizedMemoryOptions` | interface | Options for {@link createCategorizedMemory } . |
@@ -564,11 +566,12 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `DEFAULT_OPENAI_EMBEDDING_MODEL` | const | OpenAI embedding adapter (ADR D3) — built on the shared OpenAI-compatible factory.  |
 | `DEFAULT_OPENROUTER_EMBEDDING_MODEL` | const | OpenRouter embedding adapter — routes through OpenRouter's `POST /api/v1/embeddings` endpoint (OpenAI-compatible request/response shape).  |
 | `DEFAULT_VOYAGE_EMBEDDING_MODEL` | const | Voyage AI embedding adapter — `POST /v1/embeddings` at `https://api.voyageai.com` with the OpenAI-compatible `{ model, input }` request shape.  |
-| `defaultIndexPath` | function | Where the SQLite index lives when the caller does not name a path: `<cwd>/.theokit/memory/.index/memory.sqlite`.  |
+| `defaultIndexPath` | function | `<index root>/.index/memory.sqlite`.  |
 | `DiaryEntry` | interface | Dream-diary append (ADR D7).  |
-| `diaryPath` | function | Path to the dream diary, `<memory root>/dream-diary.md`.  |
-| `discoverSessionFiles` | function | List the session summaries under `sessions/`, with each path expressed relative to the memory root so the index can store a stable `sessions/<id>.md`.  |
-| `discoverWikiFiles` | function | List the `.md` files directly under `wiki/`, with each path expressed relative to the memory root so the index can store a stable `wiki/<name>.md`.  |
+| `diaryPath` | function | `<memory root>/dream-diary.md`.  |
+| `DiscoveredFile` | interface | One markdown file the corpus walk found, with the source bucket the indexer tags it with.  |
+| `discoverSessionFiles` | function | Every session summary under `<memory root>/sessions`, as `{ absolutePath, relPath }` records.  |
+| `discoverWikiFiles` | function | Every wiki supplement under `<memory root>/wiki`, as `{ absolutePath, relPath }` records.  |
 | `DreamingOptions` | interface | Dreaming sweep orchestrator (ADR D7 of memory-system-peer-project-parity).  |
 | `DreamingResult` | interface | What one sweep did.  |
 | `dropVectorIndex` | function | Drop the `embeddings` table, discarding every stored vector.  |
@@ -579,9 +582,10 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `EmbeddingRuntime` | interface | A live embedding provider, bound to one model.  |
 | `EmbeddingRuntimeStats` | interface | Counters accumulated by a runtime since it was created.  |
 | `embedMissingChunks` | function | Embed every chunk that doesn't yet have a vector. |
-| `entryHash` | function | A sha256 over the five counts of an entry, as a hex string.  |
+| `entryHash` | function | A stable hash of one entry's counts, so two sweeps that did the same work read as the same work.  |
 | `geminiMemoryEmbeddingProviderAdapter` | const | Google Gemini embeddings through Google's OpenAI-compatible surface at `/v1beta/openai/embeddings`.  |
 | `identityMatches` | function | Compare two embedding identities field by field.  |
+| `indexBudgetWarning` | function | What to say about an index that the interop partner will truncate, or `undefined` when there is nothing true to say.  |
 | `IndexManager` | class | The default memory index: SQLite for storage, FTS5 for text matching, and sqlite-vec for vectors when an embedding runtime is supplied.  |
 | `IndexStatus` | interface | A snapshot of index health.  |
 | `isLanceAvailable` | function | Test helper for {@link LanceIndex } : indicates whether the Lance module is loadable in the current environment.  |
@@ -592,30 +596,33 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `LanceMemoryAdapter` | class | Presents a `LanceIndex` as a {@link MemoryIndex } , so a consumer written against the SQLite index runs unchanged on `backend: "lance"`.  |
 | `LanceSearchHit` | interface | One Lance search result.  |
 | `LanceSearchOptions` | interface | Filters for `LanceIndex.search`.  |
-| `lanceStoragePath` | function | Test helper: re-export the storage path computation. |
+| `lanceStoragePath` | function | `<memory root>/lance`.  |
 | `legacyMemoryJsonPath` | function | Resolve the legacy JSON memory path used pre-ADR-D8 (kept for migration helpers + tests).  |
 | `lightPhase` | function | Light phase — drop facts whose embedding is too similar to one already kept. |
 | `listNotes` | function | List the `.md` files directly under `notes/`.  |
 | `loadSqliteVecExtension` | function | Load the `sqlite-vec` extension into an opened SQLite connection.  |
 | `mapOpenAICompatibleError` | function | Turn a failed OpenAI-shaped HTTP response into the typed error the SDK throws.  |
 | `MEMORY_EMBEDDING_ADAPTERS` | const | Memory embedding adapter catalog, indexed by provider id.  |
+| `MEMORY_INDEX_MAX_BYTES` | const | The byte limit the Claude Code CLI applies when it loads a `MEMORY.md`, whichever it reaches first.  |
+| `MEMORY_INDEX_MAX_LINES` | const | The line limit the Claude Code CLI applies when it loads a `MEMORY.md`.  |
 | `MemoryBackend` | type | Vector backend selector.  |
 | `MemoryChunk` | interface | A semantically meaningful slice of a markdown memory file, produced by `chunkMarkdown`.  |
 | `MemoryConfig` | interface | Per-agent memory configuration.  |
 | `MemoryDb` | interface | Thin wrapper around the SQLite driver.  |
-| `memoryDir` | function | The memory root for a workspace: `<cwd>/.theokit/memory`.  |
 | `MemoryEmbeddingProviderAdapter` | interface | Memory embedding provider adapter contract (ADR D3 of memory-system-peer-project-parity).  |
 | `MemoryFact` | interface | One remembered statement.  |
 | `MemoryFileEntry` | interface | Lightweight reference to a markdown file in the memory corpus.  |
 | `MemoryGetToolOptions` | interface | Options for {@link createMemoryGetTool } .  |
 | `MemoryIndex` | interface | The four operations both backends implement, and the type every consumer should hold.  |
+| `MemoryLocationConfig` | type | Only `directory` is read; the full config is accepted so callers pass what they already hold. |
 | `memoryMdPath` | function | Path to `MEMORY.md`, the index that points at the per-memory files — and, in stores written before #389, the flat `## Facts` list itself.  |
 | `MemoryReadResult` | interface | Result of `reader.readFile`.  |
+| `memoryReadRoots` | function | Every directory a read must cover, deduplicated and in precedence order.  |
+| `MemoryRoot` | type | A path that {@link resolveMemoryRoot } produced — the only thing the subsystem's path helpers accept.  |
 | `MemorySearchHit` | interface | Memory index manager contract — leaf types shared by `index-manager.ts` (orchestrator), `index-manager-dispatch.ts` (backend dispatch), `lance-memory-adapter.ts` (Lance backend), and `memory-index.... |
 | `MemorySearchToolOptions` | interface | Options for {@link createMemorySearchTool } . |
 | `MemoryTool` | interface | A memory tool ready to hand to the agent loop: the JSON-serialisable description an LLM sees, plus the `execute` that runs it.  |
 | `MemoryToolJson` | interface | Memory tools (`memory_search` + `memory_get`) — ADR D5 of memory-system-peer-project-parity.  |
-| `memoryWriteDir` | function | Where a NEW fact should be written.  |
 | `META_KEY_DIMENSION` | const | `meta` table key holding the vector width the `embeddings` vec0 table was created with. |
 | `META_KEY_MODEL` | const | `meta` table key holding the embedding model id the vectors were produced with. |
 | `META_KEY_PROVIDER_ID` | const | `meta` table key holding the id of the embedding provider that produced the vectors currently on disk (for example `openai`, `ollama`). |
@@ -639,8 +646,10 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `packVector` | function | Pack a Float32Array into a Buffer suitable for sqlite-vec BLOB binding. |
 | `parseRetryAfter` | function | Parse `retry-after` header in numeric-seconds form.  |
 | `parseSearchOptions` | function | Common search-options parser used by both `IndexManager.search` and `LanceMemoryAdapter.search`.  |
-| `persistActiveMemoryTranscript` | function | Write one recall transcript to `<memory root>/transcripts/active-memory/<runId>.json`, creating the parent directories and replacing the file atomically.  |
+| `persistActiveMemoryTranscript` | function | Write one active-memory recall transcript under `<memory root>/transcripts/active-memory`.  |
 | `PRAGMA_STATEMENTS` | const | Non-WAL pragmas.  |
+| `projectMemoryDir` | function | The project store: `<cwd>/.theokit/memory`.  |
+| `readAllSqliteFacts` | function | Read all facts from the SQLite memory index.  |
 | `readEmbeddingIdentity` | function | Read the embedding identity recorded in the `meta` table.  |
 | `readFacts` | function | Every memory in the store, honouring the `enabled` gate on {@link MemoryConfig } : when memory is disabled the call resolves to `[]` without touching disk.  |
 | `readFactsFromMarkdown` | function | Every memory in the store: the per-memory files, plus any legacy `## Facts` bullets still in `MEMORY.md`.  |
@@ -648,17 +657,19 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `readMemoryFileBounded` | function | Read a bounded slice of a text file and report what was left behind.  |
 | `redactSecrets` | function | Canonical credential-redaction primitive (ADR D68).  |
 | `remPhase` | function | REM phase — single-link agglomerative clustering by cosine similarity. |
-| `renderDiaryEntry` | function | Render one entry as the markdown block {@link appendDiaryEntry } writes: an h2 heading carrying the ISO timestamp, then a bullet list of the counts, prefixed by the first eight hex characters of {@... |
+| `renderDiaryEntry` | function | One diary entry as the markdown that gets appended: a timestamp heading, the short entry hash, and the counts the sweep produced.  |
 | `resetMigrationStateForTests` | function | Test-only — reset the in-process migration flag map. |
+| `resolveMemoryRoot` | function | The memory root for this agent: `memory.directory` when set, the project store otherwise.  |
 | `runActiveMemory` | function | Run one blocking recall before the system prompt is assembled, and report what happened.  |
 | `RunActiveMemoryArgs` | interface | Everything {@link runActiveMemory } needs for one attempt.  |
 | `runDreamingSweep` | function | Run one consolidation sweep over `MEMORY.md`: drop near-duplicate facts, cluster what is left, write a consolidated note under `notes/`, and append a diary entry.  |
 | `SCHEMA_STATEMENTS` | const | SQLite schema for the memory index.  |
 | `SearchOptions` | interface | Search tuning.  |
 | `SessionFile` | interface | Session summary discovery (ADR D20).  |
-| `sessionsDir` | function | Path to `<memory root>/sessions`, where one markdown summary per finished run is written.  |
+| `sessionsDir` | function | `<memory root>/sessions`.  |
 | `SessionSummaryInput` | interface | Per-run session summary writer (ADR D20).  |
-| `sessionSummaryPath` | function | Path of the summary file for a run.  |
+| `sessionSummaryPath` | function | The file one run's summary occupies: `<memory root>/sessions/<safe-id>.md`.  |
+| `SqliteFactRow` | interface | One row of the SQLite memory index, as the Lance migration reads it: the chunk plus the tenant columns the target table needs.  |
 | `SyncResult` | interface | What one `sync()` did.  |
 | `TenantContext` | interface | T4.9 — Tenant isolation context for cache key derivation.  |
 | `truncateRaw` | function | Truncate raw response body to ~2KB and redact known credential patterns so it can ride inside `ErrorMetadata.raw` without ballooning logs OR leaking tokens.  |
@@ -667,7 +678,7 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `VectorHitRow` | interface | One row of a vec0 KNN result: the chunk id and its raw distance from the query vector.  |
 | `vectorSearch` | function | Run a k-nearest-neighbour query against the `embeddings` table and return the matches ordered by ascending distance (closest first).  |
 | `voyageMemoryEmbeddingProviderAdapter` | const | Voyage AI embeddings, over the standard OpenAI wire.  |
-| `wikiDir` | function | Path to `<memory root>/wiki`, the read-only supplement directory.  |
+| `wikiDir` | function | `<memory root>/wiki`.  |
 | `WikiFile` | interface | Wiki supplement discovery (ADR Phase 10 of memory-system-peer-project-parity).  |
 | `writeEmbeddingIdentity` | function | Record the embedding identity in the `meta` table, upserting each of the three keys.  |
 | `writeSessionSummary` | function | Write a session summary file.  |
@@ -1009,15 +1020,44 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 
 | Symbol | Kind | Summary |
 |---|---|---|
+| `ActiveMemoryTranscript` | interface | Optional on-disk persistence for Active Memory recall transcripts (ADR D6).  |
+| `appendDiaryEntry` | function | Append one sweep's entry to `<memory root>/dream-diary.md`, creating the file with its header when this is the first sweep.  |
 | `appendFact` | function | Record a fact, honouring the `enabled` gate on {@link MemoryConfig } : when memory is disabled the call resolves without touching disk.  |
 | `appendFactToMarkdown` | function | Write a fact as its own memory file and point the `MEMORY.md` index at it.  |
+| `asMemoryRoot` | function | Treat a directory as a memory root without resolving one.  |
 | `claudeProjectMemoryDir` | function | Where the Claude Code CLI keeps THIS project's memories.  |
-| `memoryDir` | function | The memory root for a workspace: `<cwd>/.theokit/memory`.  |
+| `collectMarkdownFiles` | function | 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.  |
+| `defaultIndexPath` | function | `<index root>/.index/memory.sqlite`.  |
+| `DiaryEntry` | interface | Dream-diary append (ADR D7).  |
+| `diaryPath` | function | `<memory root>/dream-diary.md`.  |
+| `DiscoveredFile` | interface | One markdown file the corpus walk found, with the source bucket the indexer tags it with.  |
+| `discoverSessionFiles` | function | Every session summary under `<memory root>/sessions`, as `{ absolutePath, relPath }` records.  |
+| `discoverWikiFiles` | function | Every wiki supplement under `<memory root>/wiki`, as `{ absolutePath, relPath }` records.  |
+| `entryHash` | function | A stable hash of one entry's counts, so two sweeps that did the same work read as the same work.  |
+| `indexBudgetWarning` | function | What to say about an index that the interop partner will truncate, or `undefined` when there is nothing true to say.  |
+| `lanceStoragePath` | function | `<memory root>/lance`.  |
+| `MEMORY_INDEX_MAX_BYTES` | const | The byte limit the Claude Code CLI applies when it loads a `MEMORY.md`, whichever it reaches first.  |
+| `MEMORY_INDEX_MAX_LINES` | const | The line limit the Claude Code CLI applies when it loads a `MEMORY.md`.  |
+| `MemoryLocationConfig` | type | Only `directory` is read; the full config is accepted so callers pass what they already hold. |
 | `memoryMdPath` | function | Path to `MEMORY.md`, the index that points at the per-memory files — and, in stores written before #389, the flat `## Facts` list itself.  |
-| `memoryWriteDir` | function | Where a NEW fact should be written.  |
+| `memoryReadRoots` | function | Every directory a read must cover, deduplicated and in precedence order.  |
+| `MemoryRoot` | type | A path that {@link resolveMemoryRoot } produced — the only thing the subsystem's path helpers accept.  |
 | `notesDir` | function | Path to `<memory root>/notes`, where per-topic notes and the consolidated notes a dreaming sweep writes live.  |
+| `persistActiveMemoryTranscript` | function | Write one active-memory recall transcript under `<memory root>/transcripts/active-memory`.  |
+| `projectMemoryDir` | function | The project store: `<cwd>/.theokit/memory`.  |
+| `readAllSqliteFacts` | function | Read all facts from the SQLite memory index.  |
 | `readFacts` | function | Every memory in the store, honouring the `enabled` gate on {@link MemoryConfig } : when memory is disabled the call resolves to `[]` without touching disk.  |
 | `readFactsFromMarkdown` | function | Every memory in the store: the per-memory files, plus any legacy `## Facts` bullets still in `MEMORY.md`.  |
+| `renderDiaryEntry` | function | One diary entry as the markdown that gets appended: a timestamp heading, the short entry hash, and the counts the sweep produced.  |
+| `resolveMemoryRoot` | function | The memory root for this agent: `memory.directory` when set, the project store otherwise.  |
+| `SessionFile` | interface | Session summary discovery (ADR D20).  |
+| `sessionsDir` | function | `<memory root>/sessions`.  |
+| `SessionSummaryInput` | interface | Per-run session summary writer (ADR D20).  |
+| `sessionSummaryPath` | function | The file one run's summary occupies: `<memory root>/sessions/<safe-id>.md`.  |
+| `SqliteFactRow` | interface | One row of the SQLite memory index, as the Lance migration reads it: the chunk plus the tenant columns the target table needs.  |
+| `wikiDir` | function | `<memory root>/wiki`.  |
+| `WikiFile` | interface | Wiki supplement discovery (ADR Phase 10 of memory-system-peer-project-parity).  |
+| `writeSessionSummary` | function | Write a session summary file.  |
 
 ## `@theokit/sdk/internal/persistence`
 

package/docs/memory-decisions.md

@@ -18,10 +18,10 @@ decision the next refactor deletes.
 .theokit/memory/.index/memory.sqlite   on the first send, when memory is enabled
 ```
 
-**Why it looks wrong.** With `local.sessionDir` set, memory *facts* are written to
-`<sessionDir>/projects/<encoded-cwd>/memory/` — where the CLI reads them. So a project that never
-adopted this SDK ends up with a `.theokit/` directory anyway, which reads like the "write where the
-CLI reads" promise leaking.
+**Why it looks wrong.** With `memory.directory` pointed at the CLI's store, memory *facts* are
+written to `<claudeHome>/projects/<encoded-cwd>/memory/` — where the CLI reads them. So a project
+that never adopted this SDK ends up with a `.theokit/` directory anyway, which reads like the
+"write where the CLI reads" promise leaking.
 
 **Why it is right.** What lands in `.theokit/` is this SDK's own state, and neither piece has a
 Claude Code shape to be written in:
@@ -178,8 +178,9 @@ entries, ~3.2 KB per entry. Feeding the largest — 66 entries, 275 KB on disk
 turn's system prompt**, before the user has said anything. Nine more stores are already past the
 point where the injection exceeds a session budget.
 
-Two things make this worse than a size problem. The CLI's store is read **whether or not
-`local.sessionDir` is set**, so a consumer who never opted into CLI interop still gets it. And the
+Two things make this worse than a size problem. The CLI's store is read **unconditionally** —
+`memory.directory` decides where writes go, never what the read covers — so a consumer who never
+opted into CLI interop still gets it. And the
 cost is invisible: nothing errors, the window just fills, and the tokens are not attributed to
 memory. An earlier version of this document said "at 64 entries it does not hurt" — that was an
 assumption, and measuring it is what disproved it.
@@ -189,6 +190,42 @@ nothing — the data for a staleness signal is on disk today, unused.
 
 ---
 
+## One resolver, one root (#463)
+
+**What happens.** `memory.directory` — absolute, or `~/`-prefixed — is the only thing that decides
+where this agent's memory lives. Everything under the root follows it: `MEMORY.md`, the per-memory
+files, `notes/`, `sessions/`, `wiki/`, `transcripts/`, `dream-diary.md` and `.index/memory.sqlite`.
+
+**What it replaced.** The location used to be a side effect of `local.sessionDir`, the option that
+names the *transcript* home, on the reasoning that a consumer who set it had already opted into CLI
+interop. One option answered two questions — and of the fourteen places that computed a memory
+path, exactly one heard the second answer. `appendFact` relocated; the indexer, the `memory_get`
+path guard, `MEMORY.md`, `sessions/` and the index database did not. A relocated fact was written,
+never indexed, unreadable by the tool whose job is reading memory, and shadowed by a second
+`MEMORY.md` in the store it had left.
+
+**Why the root is a branded type.** `MemoryRoot` is `string` with a brand, produced only by
+`resolveMemoryRoot`. A cwd and a root are both strings, so without the brand the thirteen path
+helpers would go on accepting either, and the next helper added has the same even chance of taking
+the wrong one that produced this defect. The brand makes "every path derives from one resolution" a
+compiler rule instead of a convention.
+
+**The gap that remains, stated rather than hidden.** `IndexManager.open()` is a public entry point
+that takes a `cwd`, so its `memoryRoot` is optional and falls back to the default. Inside an agent
+the root is resolved once and handed to both the index and the read tool; a consumer opening the
+index by hand against a non-default directory has to pass it.
+
+**A relative `directory` is refused, not resolved.** The two plausible bases — the workspace and the
+process cwd — put the store in two different places, and picking one silently is how a store ends up
+split across both. `ConfigurationError` with code `invalid_memory_directory`.
+
+**How to check it still holds:** `tests/memory-root.test.ts`, in particular
+`test_the_indexer_scans_the_configured_directory_so_the_fact_is_searchable` and
+`test_the_project_store_gets_no_second_index_pointing_at_files_it_does_not_have` — the two halves
+that were broken.
+
+---
+
 ## Known gaps, recorded so they are not rediscovered
 
 Each row says what would close it, not only that it is open — the two invite very different work.
@@ -196,7 +233,7 @@ Each row says what would close it, not only that it is open — the two invite v
 | gap | where | what would close it |
 |---|---|---|
 | ~~The default recall path has no selection at all~~ — **closed** in `721a311f` | `local-agent-send.ts:257-272` | Closed: lexical relevance + recency, capped. Measured end to end against the real model — a 67-entry store went from ~66K to **13,606 tokens on the wire**, and the answering fact is recalled whether it is the oldest or the newest entry. |
-| The CLI's store is read whether or not `local.sessionDir` is set | `markdown-store.ts:114` — `claudeProjectMemoryDir(cwd)` is an unconditional read root | A decision, not a fix: it is deliberate (*write one, read all*, so a consumer's existing memories are never orphaned) and it means a consumer who never opted into CLI interop still receives what the CLI accumulated in that project. Cheap while the cap holds; revisit if the cap is ever removed. |
+| The CLI's store is read whether or not the consumer opted in | `storage/memory-root.ts` — `claudeProjectMemoryDir(cwd)` is an unconditional entry in `memoryReadRoots` | A decision, not a fix: it is deliberate (*write one, read all*, so a consumer's existing memories are never orphaned) and it means a consumer who never opted into CLI interop still receives what the CLI accumulated in that project. Cheap while the cap holds; revisit if the cap is ever removed. |
 | No retention of any kind — no TTL, prune, or decay | searched `ttl\|prune\|expire\|retention` across both packages: zero | A per-kind TTL plus a prune step in the sweep. Needs the kind vocabulary to mean something first (§ 2), which is why this orders before widening it. |
 | Quarantine marks but does not constrain | `memory-file.ts:96`, `memory-provider.ts:48` | Implemented: three states, and `[unconfirmed]` on entries the store counted once. **Measured against the real model and it does not close the hole** — a planted memory alone is acted on 5/5, and beside a corroborated contradiction it is still asserted ~62% of runs (n=32). Marking influences the model; it does not constrain it. The guarantee is not available at this layer: blocking an uncorroborated entry would break the promise that a fact written once is recallable next session. |
 | A planted memory can make the agent ACT | measured: `RELEASE_OVERRIDE.txt` created in 2 of 6 runs | Register the permission layer — `PermissionPlugin.create(new PermissionEngine(…))` — which blocks it every time. This is the half that IS closable at the tool boundary; the informational half above is not. Any deployment where the memory directory is writable by anything other than this agent needs it. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theokit/sdk",
-  "version": "4.62.0",
+  "version": "4.63.1",
   "description": "TypeScript SDK for the Theo agent harness — same surface, local or cloud.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/usetheokit/theokit-sdk#readme",

package/dist/agent-NVBFTY5H.js

@@ -1,55 +0,0 @@
-export { Agent } from './chunk-SKOCYA55.js';
-import './chunk-SUKXXLWD.js';
-import './chunk-YEXA3PGR.js';
-import './chunk-K2BQQ445.js';
-import './chunk-QEKI3YKI.js';
-import './chunk-MZ2FGBLZ.js';
-import './chunk-2SFBB54R.js';
-import './chunk-XN7NOENA.js';
-import './chunk-H73MEMQB.js';
-import './chunk-WCLDJSMY.js';
-import './chunk-YJDH3CKG.js';
-import './chunk-YXGAW7BB.js';
-import './chunk-3E77SX4H.js';
-import './chunk-WTMU7J4U.js';
-import './chunk-5JLFFPCH.js';
-import './chunk-G24KZRSA.js';
-import './chunk-HKCKOAIO.js';
-import './chunk-SAVIWMZB.js';
-import './chunk-KVNWIAO4.js';
-import './chunk-UCBJBJ27.js';
-import './chunk-FD2UT76F.js';
-import './chunk-4VPXM6UU.js';
-import './chunk-U54XCYG3.js';
-import './chunk-NAF4L3T6.js';
-import './chunk-RNB4APBZ.js';
-import './chunk-6X6ID4MO.js';
-import './chunk-4ERPXIVB.js';
-import './chunk-WFC26L6Y.js';
-import './chunk-7AD3ZTZL.js';
-import './chunk-QARJGQSA.js';
-import './chunk-RIAM53CP.js';
-import './chunk-UC3HT2S4.js';
-import './chunk-OC4NTGMN.js';
-import './chunk-44JAAH4X.js';
-import './chunk-FKMUFNQE.js';
-import './chunk-CQ2TQ32Y.js';
-import './chunk-CV7XMBHP.js';
-import './chunk-Q5EWJPRY.js';
-import './chunk-RUDY2GTT.js';
-import './chunk-VF7EWVDG.js';
-import './chunk-ZHPWGIUX.js';
-import './chunk-UFLD2HEV.js';
-import './chunk-AG5JPQIY.js';
-import './chunk-F7AQV62G.js';
-import './chunk-R7WIIPUR.js';
-import './chunk-2BDH744Z.js';
-import './chunk-Q4CMI2LP.js';
-import './chunk-44MBDIHG.js';
-import './chunk-UQGQFBRL.js';
-import './chunk-3OR54XG4.js';
-import './chunk-IDCKSLYH.js';
-import './chunk-T7XEKOVW.js';
-import './chunk-T7O6K6PX.js';
-//# sourceMappingURL=agent-NVBFTY5H.js.map
-//# sourceMappingURL=agent-NVBFTY5H.js.map