@theokit/sdk 4.59.0 → 4.61.0

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

@@ -0,0 +1 @@
+export declare function persistActiveMemoryTranscript(cwd: string, transcript: ActiveMemoryTranscript): Promise<void>;

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

@@ -0,0 +1,2 @@
+export declare function wikiDir(cwd: string): string;
+export declare function discoverWikiFiles(cwd: string): Promise<WikiFile[]>;

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

@@ -15,12 +15,31 @@ export interface MemoryConfig {
  *
  * A kind is never INFERRED. A wrong kind is worse than none, because it makes retention and recall
  * confident about the wrong thing — so a fact whose author did not say stays untyped.
+ *
+ * Four, not more, and deliberately: a wider vocabulary exists to drive differentiated retention, and
+ * there is no retention here to differentiate. See `packages/sdk/docs/memory-decisions.md` § 2.
  */
 export type MemoryKind = "user" | "feedback" | "project" | "reference";
 /** The four values {@link MemoryKind} admits, for runtime validation at the storage boundary. */
 export declare const MEMORY_KINDS: readonly MemoryKind[];
 export interface MemoryFact {
     text: string;
+    /**
+     * A short concept name for this memory — what the index shows in its link, and what the file is
+     * named after.
+     *
+     * Optional because the common write path has only a sentence. When absent it is derived, and the
+     * derivation is mechanical on purpose: the interop partner's names are authored by a model that
+     * knows the subject, and a heuristic will not match that. An explicit field with a fallback is
+     * honest; a fallback presented as authorship is not.
+     */
+    title?: string;
+    /**
+     * The one-line summary the index shows after the dash and the frontmatter carries.
+     *
+     * Absent means "same as `text`", which is what a single-sentence memory should produce.
+     */
+    description?: string;
     /**
      * What this fact is (#389). Absent means untyped, which is what a hand-written bullet under
      * `## Facts` stays — those files are already on disk in consumers' repositories and the store's
@@ -35,6 +54,15 @@ export interface MemoryFact {
      * from four months ago. Absent on a fact written before this existed, or hand-added.
      */
     modified?: string;
+    /**
+     * How many times this exact text has been recorded. Absent means one — uncorroborated.
+     *
+     * Gates CONFIDENCE, never presence: an uncorroborated fact is still recalled, and still
+     * reaches the model. It reaches it MARKED, so a single write cannot pass itself off as
+     * something the store has seen confirmed. Blocking it outright would break the system's
+     * central promise, which is that a fact written once is available in the next session.
+     */
+    observations?: number;
 }
 export { redactSecrets } from "../security/index.js";
 /**

package/dist/internal/runtime/memory/select-facts.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Selection for injection: rank the store and cut it, so what enters the prompt stops
+ * tracking what is on disk.
+ *
+ * Before this, `readMemoryForSend` returned every fact and the system prompt carried all of
+ * them, every turn. Measured across 99 real stores, injected bytes correlated with entry
+ * count at r = 0.958 — roughly 1,060 tokens per entry, crossing the 60 KB session budget at
+ * 16 facts. Ten stores were already past it; the largest injected ~72.6K tokens per turn,
+ * before the user's first message. That is not a ranking-quality problem, it is arithmetic.
+ *
+ * Ranking uses `modified`, which the store has always stamped, parsed and typed — and never
+ * read. The field's own doc comment says what it is for: "the whole point is to weigh a note
+ * from this morning against one from four months ago."
+ *
+ * WHY TWO BUCKETS, and not `(a.modified ?? "").localeCompare(...)`:
+ *
+ * A fact without `modified` is not old, it is UNDATED — written before the field existed, or
+ * hand-added to `MEMORY.md` by someone the store's own header invites to edit it. Sorting it
+ * as if it were from 1970 is inference wearing the costume of a default, and this codebase
+ * already rejects that reasoning one field over: "A kind is never INFERRED. A wrong kind is
+ * worse than none." The same holds here. So undated facts get a guaranteed share of the
+ * budget instead of a fabricated timestamp that buries them.
+ */
+import type { MemoryFact } from "../../memory/types.js";
+/** Defaults are the session budget of the recall contract, not tuning knobs found by trial. */
+export declare const DEFAULT_MAX_ENTRIES = 10;
+/**
+ * Characters per token, measured over the real memory corpus (99 stores, 685 entries).
+ * Named rather than folded into the byte cap, because the first version of this file did fold
+ * it in and got the cap wrong: the contract's budget is 15,000 TOKENS, "60 KB" was the
+ * rounded-off char figure someone wrote next to it, and 60 * 1024 chars is 16,605 tokens —
+ * 11% over the ceiling it claimed to enforce. A budget stated in one unit and enforced in
+ * another is a budget nobody is enforcing.
+ */
+export declare const CHARS_PER_TOKEN = 3.7;
+/** The recall contract's per-session ceiling, in the unit the contract states it in. */
+export declare const DEFAULT_MAX_TOKENS = 15000;
+/** Derived, never hand-rounded. */
+export declare const DEFAULT_MAX_BYTES: number;
+/** Share of `maxEntries` reserved for undated facts before dated ones may claim the rest. */
+export declare const DEFAULT_UNDATED_SHARE = 0.5;
+export interface SelectFactsOptions {
+    maxEntries?: number;
+    maxBytes?: number;
+    undatedShare?: number;
+    /**
+     * The turn's text. When given, facts are ranked by lexical relevance to it, fused with
+     * recency. When absent, ranking falls back to recency alone.
+     *
+     * Measured (T3, live model, 25-fact store): with recency-only ranking, a fact that answers
+     * the question is MISSED when it is the oldest entry and RECALLED when it is the newest.
+     * Recency is not relevance, and a store only has to outgrow the cap once for the difference
+     * to decide whether the agent can answer.
+     */
+    query?: string;
+}
+/**
+ * Rank and cut. Returns at most `maxEntries` facts totalling at most `maxBytes`.
+ *
+ * Neither bucket starves the other: a quota one bucket cannot fill is available to the
+ * other, so a store of only dated facts still fills the whole budget.
+ */
+export declare function selectFactsForInjection(facts: readonly MemoryFact[], options?: SelectFactsOptions): MemoryFact[];

package/dist/internal/runtime/system-prompt/sources/memory-provider.d.ts

@@ -1 +1,6 @@
-export {};
+import type { SystemPromptAssemblyContext, SystemPromptProvider } from "../types.js";
+export declare class MemoryPromptProvider implements SystemPromptProvider {
+    readonly id = "memory";
+    readonly priority = 30;
+    contribute(ctx: SystemPromptAssemblyContext): Promise<string | undefined>;
+}

package/dist/workflow.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkGNT35C5U_cjs = require('./chunk-GNT35C5U.cjs');
+var chunk6SBW4QR2_cjs = require('./chunk-6SBW4QR2.cjs');
 var chunkXWL6O3SW_cjs = require('./chunk-XWL6O3SW.cjs');
 require('./chunk-VTYY7XL5.cjs');
 require('./chunk-WJVHMTKB.cjs');
@@ -15,35 +15,35 @@ require('./chunk-NUKRL3I6.cjs');
 
 Object.defineProperty(exports, "Workflow", {
   enumerable: true,
-  get: function () { return chunkGNT35C5U_cjs.Workflow; }
+  get: function () { return chunk6SBW4QR2_cjs.Workflow; }
 });
 Object.defineProperty(exports, "WorkflowBuilder", {
   enumerable: true,
-  get: function () { return chunkGNT35C5U_cjs.WorkflowBuilder; }
+  get: function () { return chunk6SBW4QR2_cjs.WorkflowBuilder; }
 });
 Object.defineProperty(exports, "WorkflowToolError", {
   enumerable: true,
-  get: function () { return chunkGNT35C5U_cjs.WorkflowToolError; }
+  get: function () { return chunk6SBW4QR2_cjs.WorkflowToolError; }
 });
 Object.defineProperty(exports, "agentStep", {
   enumerable: true,
-  get: function () { return chunkGNT35C5U_cjs.agentStep; }
+  get: function () { return chunk6SBW4QR2_cjs.agentStep; }
 });
 Object.defineProperty(exports, "cloneWorkflow", {
   enumerable: true,
-  get: function () { return chunkGNT35C5U_cjs.cloneWorkflow; }
+  get: function () { return chunk6SBW4QR2_cjs.cloneWorkflow; }
 });
 Object.defineProperty(exports, "fn", {
   enumerable: true,
-  get: function () { return chunkGNT35C5U_cjs.fn; }
+  get: function () { return chunk6SBW4QR2_cjs.fn; }
 });
 Object.defineProperty(exports, "workflowAsTool", {
   enumerable: true,
-  get: function () { return chunkGNT35C5U_cjs.workflowAsTool; }
+  get: function () { return chunk6SBW4QR2_cjs.workflowAsTool; }
 });
 Object.defineProperty(exports, "workflowStep", {
   enumerable: true,
-  get: function () { return chunkGNT35C5U_cjs.workflowStep; }
+  get: function () { return chunk6SBW4QR2_cjs.workflowStep; }
 });
 Object.defineProperty(exports, "WorkflowAlreadyRunningError", {
   enumerable: true,

package/dist/workflow.js

@@ -1,4 +1,4 @@
-export { Workflow, WorkflowBuilder, WorkflowToolError, agentStep, cloneWorkflow, fn, workflowAsTool, workflowStep } from './chunk-XV4IZNV4.js';
+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';
 import './chunk-HY66GLM6.js';
 import './chunk-4VPXM6UU.js';

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.
 
-204 distinct code(s).
+205 distinct code(s).
 
 | Code | Kind | Raised by | Sites |
 |---|---|---|---|
@@ -88,7 +88,7 @@ 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:184` |
+| `invalid_memory_kind` | domain | ConfigurationError | `packages/sdk/src/internal/memory/storage/markdown-store.ts:233` |
 | `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` |
@@ -114,6 +114,7 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `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_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 |
 | `missing_api_key` | domain | AuthenticationError, ConfigurationError | `packages/sdk/src/agent-helpers.ts:217` +2 |

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.
 
-1126 export(s) across 45 entry point(s).
+1137 export(s) across 46 entry point(s).
 
 ## `@theokit/acp`
 
@@ -527,8 +527,8 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `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.  |
-| `appendFact` | function | Append a fact, honouring the `enabled` gate on {@link MemoryConfig } : when memory is disabled the call resolves without touching disk.  |
-| `appendFactToMarkdown` | function | Append a fact to `MEMORY.md ## Facts`.  |
+| `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.  |
 | `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). |
@@ -538,6 +538,7 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `ChunkMarkdownOptions` | interface | Split a markdown document into semantically meaningful chunks (ADR D1 of memory-system-peer-project-parity).  |
 | `CircuitBreaker` | class | Stops calling a recall path that keeps timing out.  |
 | `CircuitBreakerOptions` | interface | Consecutive-timeout circuit breaker for Active Memory recall.  |
+| `claudeProjectMemoryDir` | function | Where the Claude Code CLI keeps THIS project's memories.  |
 | `Cluster` | interface | A group of facts the REM phase judged related.  |
 | `ClusterResult` | interface | What {@link remPhase } produced.  |
 | `cohereMemoryEmbeddingProviderAdapter` | const | Cohere embeddings.  |
@@ -608,12 +609,13 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `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.  |
-| `memoryMdPath` | function | Path to `MEMORY.md`, the single file holding the flat `## Facts` list.  |
+| `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`.  |
 | `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`). |
@@ -624,7 +626,7 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `MigrationResult` | interface | Outcome of {@link migrateLegacyJson } .  |
 | `mistralMemoryEmbeddingProviderAdapter` | const | Mistral embeddings, over the standard OpenAI wire.  |
 | `NoteFile` | interface | One note discovered under `notes/`: its file name without the `.md` suffix, and its absolute path. |
-| `notesDir` | function | Path to `<memory root>/notes`, where per-topic notes and the consolidated notes written by a dreaming sweep live.  |
+| `notesDir` | function | Path to `<memory root>/notes`, where per-topic notes and the consolidated notes a dreaming sweep writes live.  |
 | `ollamaMemoryEmbeddingProviderAdapter` | const | Embeddings from a local Ollama instance — the only adapter in the catalog with `transport: "local"`, and the one to choose when the corpus must not leave the machine or when there is no API key to ... |
 | `OpenAiCompatibleConfig` | interface | What one provider adapter tells {@link createOpenAiCompatibleRuntime } about its wire: where to POST, which environment variables carry the key and the base URL, which model to use by default, and ... |
 | `openAiMemoryEmbeddingProviderAdapter` | const | OpenAI embeddings — `text-embedding-3-small` (1536), `text-embedding-3-large` (3072) and `text-embedding-ada-002` (1536).  |
@@ -640,8 +642,8 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `persistActiveMemoryTranscript` | function | Write one recall transcript to `<memory root>/transcripts/active-memory/<runId>.json`, creating the parent directories and replacing the file atomically.  |
 | `PRAGMA_STATEMENTS` | const | Non-WAL pragmas.  |
 | `readEmbeddingIdentity` | function | Read the embedding identity recorded in the `meta` table.  |
-| `readFacts` | function | Configuration-aware accessors honoring the existing MemoryConfig contract. |
-| `readFactsFromMarkdown` | function | Read facts from `MEMORY.md`'s `## Facts` section.  |
+| `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`.  |
 | `ReadFileOptions` | interface | Inputs for {@link readMemoryFileBounded } .  |
 | `readMemoryFileBounded` | function | Read a bounded slice of a text file and report what was left behind.  |
 | `redactSecrets` | function | Canonical credential-redaction primitive (ADR D68).  |
@@ -1003,6 +1005,20 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `LruEmbeddingCache` | class | Bounded in-memory LRU cache for embeddings, keyed by `sha256(text)` (or any stable key the caller chooses).  |
 | `OpenAiCompatibleConfig` | interface | What one provider adapter tells {@link createOpenAiCompatibleRuntime } about its wire: where to POST, which environment variables carry the key and the base URL, which model to use by default, and ... |
 
+## `@theokit/sdk/internal/memory-store`
+
+| Symbol | Kind | Summary |
+|---|---|---|
+| `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.  |
+| `claudeProjectMemoryDir` | function | Where the Claude Code CLI keeps THIS project's memories.  |
+| `memoryDir` | function | The memory root for a workspace: `<cwd>/.theokit/memory`.  |
+| `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.  |
+| `notesDir` | function | Path to `<memory root>/notes`, where per-topic notes and the consolidated notes a dreaming sweep writes live.  |
+| `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`.  |
+
 ## `@theokit/sdk/internal/persistence`
 
 | Symbol | Kind | Summary |

package/docs/memory-decisions.md

@@ -0,0 +1,207 @@
+# Memory subsystem — decisions that are not obvious from the code
+
+Five decisions that a reader would otherwise be right to call bugs. Each names where the behaviour
+lives, so the next person to touch it can disagree on purpose rather than "fix" it by accident.
+
+Written after a conformance audit against an external memory contract found that three of these
+existed only in commit messages and one only in a conversation. A decision nobody can find is a
+decision the next refactor deletes.
+
+---
+
+## 1. Running an agent creates `.theokit/`, even when memory goes to the Claude Code directory
+
+**What happens.** Reading a Claude Code project creates nothing. Running an agent creates:
+
+```
+.theokit/agents/registry.json          on Agent.create
+.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 is right.** What lands in `.theokit/` is this SDK's own state, and neither piece has a
+Claude Code shape to be written in:
+
+- `agents/registry.json` is the live-agent address book (`internal/runtime/registry/agent-registry.ts`).
+  The CLI has no equivalent.
+- `memory/.index/memory.sqlite` is the search index (`sdk-memory/internal/index/index-db.ts:84-91`).
+  **The CLI has no index format**, so there is no CLI location that could hold it. Putting it beside
+  the facts in the CLI's directory would put a binary artefact the CLI does not understand inside a
+  directory the CLI manages.
+
+The facts — the thing a user recorded and would lose — go where the CLI reads. The index is derived
+data that can be rebuilt from them.
+
+**How to check it still holds:** `tests/claude-code-e2e-compat.test.ts`, the pair
+`test_reading_a_cli_project_creates_nothing_in_it` /
+`test_running_an_agent_creates_theokit_and_only_sdk_state_in_it`. The second exists so the first is
+not vacuous — it asserts the directory contains *only* `agents` and `memory`.
+
+---
+
+## 2. Four memory kinds, and a kind is never inferred
+
+`internal/memory/types.ts:32` declares `user | feedback | project | reference`, validated at the
+storage boundary (`internal/memory/storage/markdown-store.ts:195`, `invalid_memory_kind`).
+
+**Known divergence.** An external contract this SDK was audited against specifies **nine** kinds in
+three retention buckets (atomic / consolidatable / lifecycle-managed). This SDK has four.
+
+**Why it has not been widened.** The nine exist to drive differentiated retention, and **this SDK has
+no retention at all** — no TTL, no pruning, no decay (searched `ttl|prune|expire|retention` across
+both packages; the only hits are the recall result cache, which expires *results*, not entries).
+Nine names over a regime where nothing expires are nine names for one behaviour. Retention has to
+exist before a vocabulary that differentiates it is worth anything.
+
+> **One of this argument's two legs has since been removed, and the note stays so the argument
+> cannot be defended with it later.** An earlier version of this section also said "and no buckets".
+> That stopped being true in `a655ac4d`: `dreaming/phases.ts:48-49` now has `ATOMIC_KINDS` and
+> `CONSOLIDATABLE_KINDS`, and `dedupPolicy` grades three levels by them. The buckets exist; what
+> still does not exist is the retention they would govern.
+
+**The stronger reason, found after the first one weakened: the four are not a subset, they are the
+partner's vocabulary.** This store's format is shared with the Claude Code CLI, and every memory the
+CLI has written on one developer machine — 688 files, 2026-08 — carries one of exactly these four:
+
+```
+425 project    167 feedback    74 reference    7 user    (15 with no type)
+```
+
+Zero others. Adding a fifth value means writing files whose `type` the interop partner has never
+emitted. That is evidence about what it WRITES, not proof about what it ACCEPTS on read — but it
+means there is no precedent, and the burden belongs to whoever adds one unilaterally.
+
+**`failure_heuristic` is the one the retention argument does not cover, and the interop argument
+does.** It changes *what is written* (a trigger→resolution pair) rather than how an entry expires, so
+"no retention to differentiate" says nothing about it — and nothing has adopted it (`grep
+failure_heuristic packages/sdk/src` → zero). It is not declined on retention grounds; it is held by
+the same shared-format question as the other four, and unblocking it means establishing what the CLI
+does with a `type` it does not emit.
+
+**The part that is not negotiable:** a kind is never inferred (`types.ts:29`). A wrong kind is worse
+than none, because it makes retention and recall confident about the wrong thing.
+
+---
+
+## 3. Re-recording a fact overwrites it; there is no `Invalidated` state
+
+`markdown-store.ts:204` writes `<slug>.md` through `replaceFileAtomic`, and `nextIndex`
+(`:222-235`) keeps exactly one index line per name.
+
+**Known divergence.** The same external contract requires a contradiction to produce an
+`Invalidated` entry plus a supersession chain, not an overwrite.
+
+**Why the index is right as it is.** The index is a map from memory to file. Two lines for one file
+is a map that disagrees with itself, and the CLI reads that index.
+
+**What the entry is NAMED by changed, and it is worth knowing why.** The slug and the index title
+used to be the fact's whole sentence. They are now a short topic name — `MemoryFact` carries optional
+`title` and `description` so a writer can author them, and derives them when it does not. The
+derivation is mechanical on purpose and does not pretend to be authorship, the same rule this store
+applies to `kind`.
+
+**Two distinct facts that share a subject now coexist; they used to overwrite each other.** A topic
+slug is a lossy summary, and lossy summaries collide: `"fact A"`, `"fact B"` and `"fact C"` all
+derive `fact`. Naming by the whole sentence made collisions rare by accident; naming by subject made
+them ordinary. `resolveName` (`markdown-store.ts:280`) settles it by the only thing that can — the
+text: the same text keeps the same file and increments corroboration, different text takes
+`topic-2`. Found by the golden `multiple appends each get a file`, not by review — the failure was
+silent data loss, and nothing about the reasoning would have surfaced it.
+
+So the section heading stays true for what it describes, re-recording the *same* fact, and the case
+it never covered is now covered.
+
+That change closed #446, where a passphrase the model had just refused to store was written into the
+**filename** and the index line. The reason it works is that it is not a rule about secrets: a rule
+about secrets has to recognise one, and `redactSecrets` had already demonstrated it does not
+recognise `sirius-zzq417`. Naming the memory by its **subject** drops the tail of the sentence
+whatever the tail happens to be. Closed by construction, not by detection — which is the only kind
+of closure available when the dangerous input is indistinguishable from a safe one.
+
+**Why this is still a gap.** "The index names the current entry" and "the store keeps the
+supersession chain" are not in conflict — they are different files. The resolution, when it is
+built, is the index pointing at the current entry while the entry file carries its own chain. What
+exists today is only the first half.
+
+---
+
+## 4. The session transcript is a DAG, not a linear log
+
+`internal/persistence/session-transcript.ts:4-11,77-78` — records carry `uuid`/`parentUuid`, and
+`appendCompactBoundary` starts a new root.
+
+**Deliberate and forced.** The format IS the Claude Code record shape. Bidirectional CLI
+compatibility is a product requirement, so a linear session model is not available to choose: it
+would make transcripts this SDK writes unreadable by the CLI and vice versa.
+
+Where an external contract prescribes a linear session model, this is a documented middle-ground —
+the contract is deciding a question that a SDK with an imposed wire format does not get to answer.
+
+---
+
+## 5. Recall is lexical by default; dense vectors only when a consumer asks for them
+
+Two different things are called recall:
+
+- **Default.** `internal/local-agent/local-agent-send.ts:257-272` reads the store, then ranks and
+  cuts it through `selectFactsForInjection` — lexical relevance against the user's message, fused
+  with recency, capped at 10 entries and a byte budget derived from 15,000 tokens. No embeddings on
+  this path at all (`runtime/memory/select-facts.ts:117-118`).
+- **The `memory_search` tool.** Its index is NOT opt-in: `local-agent-memory.ts:82-98` opens
+  `IndexManager` whenever `memory.enabled` is true. The dense vectors are — `maybeCreateEmbeddingRuntime`
+  (`:198-200`) returns `undefined` unless `memory.index.embedding` is configured, so by default the
+  index runs text-only. The `vectorWeight ?? 0.6` blend at `index-manager-helpers.ts:21` weighs a
+  vector that, unconfigured, was never computed.
+
+So no dense vector participates in scoring under a default configuration. One does only when a
+consumer names an embedding provider.
+
+**Known divergence,** on the opt-in path: the external contract forbids dense vectors in agent-memory
+recall below a measured threshold (>1000 entries *and* demonstrated lexical degradation). Neither has
+been measured here.
+
+**The bigger gap WAS the default path, and it was not this divergence.** A contract arbitrating
+*between* retrieval methods does not cover the absence of one — and until `721a311f` there was no
+method on this path at all. That is fixed; the history is kept because the failure mode is worth
+recognising again, and because it explains why the ranking signal has to depend on the question. A
+first version cut by recency alone, and a live run showed the answering fact dropped for being old
+rather than irrelevant. Bounding cost and choosing what survives are two jobs, and a cap does only
+the first.
+
+**What that default path used to inject, measured 2026-08 against the published artefact.** 100 real stores on one developer machine, 687
+entries, ~3.2 KB per entry. Feeding the largest — 66 entries, 275 KB on disk — to
+`readFactsFromMarkdown` returns all 66 and **246K characters, roughly 66K tokens injected into every
+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
+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.
+
+`metadata.modified` is already written (`markdown-store.ts:210`) and parsed (`:177`) and consumed by
+nothing — the data for a staleness signal is on disk today, unused.
+
+---
+
+## 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.
+
+| 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. |
+| 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. |
+| `description` is written as a copy of the body | `markdown-store.ts:205-211` — the *reader* (`:174-177`) already handles a distinct description correctly | Stop writing one when nobody declared it. The role is a one-line recall aid; deriving it mechanically would be inferring the situation, which § 2's rule already forbids for `kind`. Absent is a valid state and the reader already falls back to the body. |
+| The topic-name deriver filters English function words only | `memory-file.ts:73` | A store in another language keeps that language's function words in the slug and the index title — `de`, `do`, `para` survive, so the name is longer and noisier. **Never lossy:** collisions are caught by `resolveName` comparing text, not by the stopword list. Real stores here are bilingual, so this is a partial parity, not a complete one. Closes with a per-language list, or by not needing one. |
+| The dream sweep never filters by kind before dedup | `dreaming/phases.ts:34` — `lightPhase` never reads `kind` | Partition by kind before `lightPhase`. Nothing is deleted today, but a consolidated note can blend two distinct entries, and the note is what search returns. |
+| The dream sweep does not update the index | `dreaming/run.ts:53-96` writes `notes/` and never syncs | An `IndexManager.sync` after `writeConsolidatedNotes`. |
+| Recall fires every turn, cached on query hash, not on store manifest | `internal/local-agent/local-agent-memory.ts:87`; `sdk-memory/internal/active-memory/active-memory-cache.ts:66` | A second skip condition beside the existing one — hash of the store manifest, so an unchanged store skips even when the question changes. The query cache is not wrong; it answers a different question. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theokit/sdk",
-  "version": "4.59.0",
+  "version": "4.61.0",
   "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",
@@ -288,6 +288,16 @@
         "default": "./dist/internal/memory/adapters/index.cjs"
       }
     },
+    "./internal/memory-store": {
+      "import": {
+        "types": "./dist/internal/memory/storage/index.d.ts",
+        "default": "./dist/internal/memory/storage/index.js"
+      },
+      "require": {
+        "types": "./dist/internal/memory/storage/index.d.cts",
+        "default": "./dist/internal/memory/storage/index.cjs"
+      }
+    },
     "./a2a": {
       "import": {
         "types": "./dist/a2a/index.d.ts",