@theokit/sdk-memory 0.3.3 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog — @theokit/sdk-memory
 
+## 0.4.0
+
+### Minor Changes
+
+- 4aa19d1: Installing this package no longer makes the memory store unreadable.
+
+  `Memory.runDreamingSweep` in `@theokit/sdk` replaces its own store with this package's whenever this
+  package is installed. This package carried a full copy, and the copy stayed on the layout that
+  predates the file-per-memory format — so it could not read anything the SDK had written. The sweep
+  reported `factsBefore: 0`, a number indistinguishable from an empty store (#430). Nothing threw.
+
+  The store is now imported from `@theokit/sdk/internal/memory-store` rather than copied, which is why
+  the `@theokit/sdk` peer floor rises to `>=4.60.0`: that is the version the sub-path first ships in,
+  and importing a path an admitted version does not export is a load-time crash, not a type error.
+
+  The exported signatures are supersets of what this package exposed before — the added parameters are
+  optional — so existing calls are unaffected. What changes is that `appendFactToMarkdown` now writes a
+  file per memory with `MEMORY.md` as its index, instead of a bullet under `## Facts`. Bullets written
+  by earlier versions are still read.
+
+  The promise this broke — _"the fallback is not a degraded mode"_ — now has a test. It had none, which
+  is why the two copies drifted for two format changes without anything going red.
+
 ## 0.3.3
 
 ### Patch Changes

package/dist/index.cjs

@@ -4,10 +4,11 @@ var promises = require('fs/promises');
 var path = require('path');
 var sdk = require('@theokit/sdk');
 var persistence = require('@theokit/sdk/persistence');
-var pathSafety = require('@theokit/sdk/path-safety');
+var memoryStore = require('@theokit/sdk/internal/memory-store');
 var crypto = require('crypto');
 var memoryAdapters = require('@theokit/sdk/internal/memory-adapters');
 var errors = require('@theokit/sdk/errors');
+var pathSafety = require('@theokit/sdk/path-safety');
 var fs = require('fs');
 var module$1 = require('module');
 
@@ -240,114 +241,20 @@ function createInMemoryMarkdownProvider() {
     }
   };
 }
-function redactSecrets(text, opts) {
-  return sdk.Security.redact(text, opts);
-}
-function legacyMemoryJsonPath(cwd, config) {
-  if (config.storePath !== void 0) {
-    return path.resolve(cwd, config.storePath);
-  }
-  const namespace = pathSafety.sanitizeIdentifier(config.namespace ?? "default");
-  const scope = pathSafety.sanitizeIdentifier(config.scope ?? "agent", { maxLen: 16 });
-  const userId = pathSafety.sanitizeIdentifier(config.userId ?? "default");
-  return pathSafety.safePathJoin(cwd, ".theokit", "memory", namespace, `${scope}-${userId}.json`);
-}
-
-// src/internal/store/markdown-store.ts
-var MEMORY_MD_HEADER = "# Memory\n\n> Auto-managed by @theokit/sdk. Edit freely \u2014 the SDK reads from here.\n";
-var FACTS_HEADING = "## Facts";
-function memoryDir(cwd) {
-  return path.join(cwd, ".theokit", "memory");
-}
-function memoryMdPath(cwd) {
-  return path.join(memoryDir(cwd), "MEMORY.md");
-}
-function notesDir(cwd) {
-  return path.join(memoryDir(cwd), "notes");
-}
-async function readFactsFromMarkdown(cwd) {
-  let raw;
-  try {
-    raw = await promises.readFile(memoryMdPath(cwd), "utf8");
-  } catch {
-    return [];
-  }
-  return parseFactsSection(raw);
-}
-function appendFactToMarkdown(cwd, fact) {
-  return persistence.withCwdMutex(memoryDir(cwd), async () => {
-    const path = memoryMdPath(cwd);
-    let raw = "";
-    try {
-      raw = await promises.readFile(path, "utf8");
-    } catch {
-      raw = "";
-    }
-    const sanitized = redactSecrets(fact.text);
-    const next = insertFactBullet(raw, sanitized);
-    await promises.mkdir(memoryDir(cwd), { recursive: true });
-    await persistence.replaceFileAtomic(path, next);
-  });
-}
 async function listNotes(cwd) {
   let entries = [];
   try {
-    entries = await promises.readdir(notesDir(cwd));
+    entries = await promises.readdir(memoryStore.notesDir(cwd));
   } catch {
     return [];
   }
-  return entries.filter((name) => name.endsWith(".md")).map((name) => ({ slug: name.replace(/\.md$/, ""), path: path.join(notesDir(cwd), name) }));
-}
-function parseFactsSection(raw) {
-  const idx = raw.indexOf(FACTS_HEADING);
-  if (idx === -1) return [];
-  const tail = raw.slice(idx + FACTS_HEADING.length);
-  const nextHeading = tail.search(/\n#{1,2}\s/);
-  const block = nextHeading === -1 ? tail : tail.slice(0, nextHeading);
-  return block.split("\n").map((line) => line.trim()).filter((line) => line.startsWith("- ")).map((line) => ({ text: line.slice(2).trim() }));
-}
-function insertFactBullet(raw, fact) {
-  const bullet = `- ${fact}`;
-  if (raw.length === 0) {
-    return `${MEMORY_MD_HEADER}
-${FACTS_HEADING}
-
-${bullet}
-`;
-  }
-  const idx = raw.indexOf(FACTS_HEADING);
-  if (idx === -1) {
-    const sep = raw.endsWith("\n") ? "" : "\n";
-    return `${raw}${sep}
-${FACTS_HEADING}
-
-${bullet}
-`;
-  }
-  const after = idx + FACTS_HEADING.length;
-  const nextHeading = raw.slice(after).search(/\n#{1,2}\s/);
-  if (nextHeading === -1) {
-    const trailing = raw.endsWith("\n") ? "" : "\n";
-    return `${raw}${trailing}${bullet}
-`;
-  }
-  const insertAt = after + nextHeading;
-  return `${raw.slice(0, insertAt)}
-${bullet}${raw.slice(insertAt)}`;
-}
-async function readFacts(cwd, config) {
-  if (!config.enabled) return [];
-  return readFactsFromMarkdown(cwd);
-}
-async function appendFact(cwd, config, fact) {
-  if (!config.enabled) return;
-  await appendFactToMarkdown(cwd, fact);
+  return entries.filter((name) => name.endsWith(".md")).map((name) => ({ slug: name.replace(/\.md$/, ""), path: path.join(memoryStore.notesDir(cwd), name) }));
 }
 
 // src/internal/store/transcript-store.ts
 async function persistActiveMemoryTranscript(cwd, transcript) {
   try {
-    const dir = path.join(memoryDir(cwd), "transcripts", "active-memory");
+    const dir = path.join(memoryStore.memoryDir(cwd), "transcripts", "active-memory");
     const file = path.join(dir, `${transcript.runId}.json`);
     await persistence.atomicWriteJson(file, transcript);
   } catch (cause) {
@@ -951,6 +858,20 @@ var MEMORY_EMBEDDING_ADAPTERS = {
   jina: jinaMemoryEmbeddingProviderAdapter,
   gemini: geminiMemoryEmbeddingProviderAdapter
 };
+function redactSecrets(text, opts) {
+  return sdk.Security.redact(text, opts);
+}
+function legacyMemoryJsonPath(cwd, config) {
+  if (config.storePath !== void 0) {
+    return path.resolve(cwd, config.storePath);
+  }
+  const namespace = pathSafety.sanitizeIdentifier(config.namespace ?? "default");
+  const scope = pathSafety.sanitizeIdentifier(config.scope ?? "agent", { maxLen: 16 });
+  const userId = pathSafety.sanitizeIdentifier(config.userId ?? "default");
+  return pathSafety.safePathJoin(cwd, ".theokit", "memory", namespace, `${scope}-${userId}.json`);
+}
+
+// src/internal/adapter-http-error.ts
 var RAW_MAX_BYTES = 2048;
 function parseRetryAfter(headers) {
   if (headers === void 0) return void 0;
@@ -1039,7 +960,7 @@ function mapOpenAiStatusToCode(status, body) {
 function formatMessage(providerId, status, code) {
   return `${providerId} API error: ${code} (HTTP ${status})`;
 }
-var FACTS_HEADING2 = "## Facts";
+var FACTS_HEADING = "## Facts";
 function createCategorizedMemory(options) {
   const { root, categories } = options;
   validateCategories(categories);
@@ -1113,7 +1034,7 @@ function header(category) {
 category: ${category}
 ---
 
-${FACTS_HEADING2}
+${FACTS_HEADING}
 `;
 }
 async function readFileOrEmpty(path) {
@@ -1137,24 +1058,24 @@ function decodeFact(text) {
   );
 }
 function parseFactBullets(raw) {
-  const idx = raw.indexOf(FACTS_HEADING2);
+  const idx = raw.indexOf(FACTS_HEADING);
   if (idx === -1) return [];
-  const tail = raw.slice(idx + FACTS_HEADING2.length);
+  const tail = raw.slice(idx + FACTS_HEADING.length);
   const nextHeading = tail.search(/\n#{1,2}\s/);
   const block = nextHeading === -1 ? tail : tail.slice(0, nextHeading);
   return block.split("\n").map((line) => line.trim()).filter((line) => line.startsWith("- ")).map((line) => line.slice(2).trim());
 }
 function appendBullet(raw, text) {
   const bullet = `- ${text}`;
-  const idx = raw.indexOf(FACTS_HEADING2);
+  const idx = raw.indexOf(FACTS_HEADING);
   if (idx === -1) {
     const sep = raw.endsWith("\n") ? "" : "\n";
-    return `${raw}${sep}${FACTS_HEADING2}
+    return `${raw}${sep}${FACTS_HEADING}
 
 ${bullet}
 `;
   }
-  const after = idx + FACTS_HEADING2.length;
+  const after = idx + FACTS_HEADING.length;
   const nextHeading = raw.slice(after).search(/\n#{1,2}\s/);
   if (nextHeading === -1) {
     const trailing = raw.endsWith("\n") ? "" : "\n";
@@ -1166,7 +1087,7 @@ ${bullet}
 ${bullet}${raw.slice(insertAt)}`;
 }
 function diaryPath(cwd) {
-  return path.join(memoryDir(cwd), "dream-diary.md");
+  return path.join(memoryStore.memoryDir(cwd), "dream-diary.md");
 }
 function renderDiaryEntry(entry) {
   const stamp = new Date(entry.timestampMs).toISOString();
@@ -1311,7 +1232,7 @@ async function runInner(options) {
   const now = options.now ?? Date.now;
   const timestampMs = now();
   try {
-    const facts = await readFactsFromMarkdown(options.cwd);
+    const facts = await memoryStore.readFactsFromMarkdown(options.cwd);
     if (facts.length === 0) {
       return emptyResult("skipped");
     }
@@ -1345,10 +1266,10 @@ async function runInner(options) {
 }
 async function writeConsolidatedNotes(cwd, clusters, timestampMs) {
   if (clusters.length === 0) return 0;
-  const notesDir2 = path.join(memoryDir(cwd), "notes");
-  await promises.mkdir(notesDir2, { recursive: true });
+  const notesDir3 = path.join(memoryStore.memoryDir(cwd), "notes");
+  await promises.mkdir(notesDir3, { recursive: true });
   const isoSlug = new Date(timestampMs).toISOString().replace(/[^\dT]/g, "-");
-  const file = path.join(notesDir2, `dreamed-${isoSlug}.md`);
+  const file = path.join(notesDir3, `dreamed-${isoSlug}.md`);
   const body = deepPhase(clusters, timestampMs);
   await persistence.replaceFileAtomic(file, body);
   return 1;
@@ -1498,7 +1419,7 @@ function findWordBoundarySplit(text, maxChars) {
 }
 var MAX_TURN_CHARS = 2e3;
 function sessionsDir(cwd) {
-  return path.join(memoryDir(cwd), "sessions");
+  return path.join(memoryStore.memoryDir(cwd), "sessions");
 }
 function sessionSummaryPath(cwd, runId) {
   return path.join(sessionsDir(cwd), `${sanitizeRunId2(runId)}.md`);
@@ -1545,7 +1466,7 @@ async function discoverSessionFiles(cwd) {
   } catch {
     return [];
   }
-  const root = memoryDir(cwd);
+  const root = memoryStore.memoryDir(cwd);
   return entries.filter((entry) => entry.endsWith(".md")).map((entry) => {
     const absolutePath = path.join(sessionsDir(cwd), entry);
     return {
@@ -1559,7 +1480,7 @@ function relativeToRoot(root, absolutePath) {
   return absolutePath;
 }
 function wikiDir(cwd) {
-  return path.join(memoryDir(cwd), "wiki");
+  return path.join(memoryStore.memoryDir(cwd), "wiki");
 }
 async function discoverWikiFiles(cwd) {
   let entries;
@@ -1568,7 +1489,7 @@ async function discoverWikiFiles(cwd) {
   } catch {
     return [];
   }
-  const root = memoryDir(cwd);
+  const root = memoryStore.memoryDir(cwd);
   return entries.filter((entry) => entry.endsWith(".md")).map((entry) => ({
     absolutePath: path.join(wikiDir(cwd), entry),
     relPath: path.join("wiki", entry)
@@ -2146,22 +2067,22 @@ function blendScores(hit, vectorScore, weights) {
   };
 }
 async function collectMarkdownFiles(cwd) {
-  const root = memoryDir(cwd);
+  const root = memoryStore.memoryDir(cwd);
   const results = [];
   try {
-    await promises.stat(memoryMdPath(cwd));
+    await promises.stat(memoryStore.memoryMdPath(cwd));
     results.push({
-      absolutePath: memoryMdPath(cwd),
-      relPath: path.relative(root, memoryMdPath(cwd)),
+      absolutePath: memoryStore.memoryMdPath(cwd),
+      relPath: path.relative(root, memoryStore.memoryMdPath(cwd)),
       source: "memory"
     });
   } catch {
   }
   try {
-    const entries = await promises.readdir(notesDir(cwd));
+    const entries = await promises.readdir(memoryStore.notesDir(cwd));
     for (const entry of entries) {
       if (!entry.endsWith(".md")) continue;
-      const abs = path.join(notesDir(cwd), entry);
+      const abs = path.join(memoryStore.notesDir(cwd), entry);
       results.push({ absolutePath: abs, relPath: path.relative(root, abs), source: "memory" });
     }
   } catch {
@@ -2349,7 +2270,7 @@ async function readLegacyFacts(jsonPath) {
 }
 async function writeMigratedFacts(cwd, jsonPath, facts) {
   try {
-    for (const fact of facts) await appendFactToMarkdown(cwd, fact);
+    for (const fact of facts) await memoryStore.appendFactToMarkdown(cwd, fact);
     await promises.unlink(jsonPath).catch(() => void 0);
     process.stderr.write(
       `[theokit-sdk] migrated ${facts.length} fact(s) from ${jsonPath} to MEMORY.md
@@ -2372,7 +2293,7 @@ async function migrateLegacyJson(cwd, config) {
   if (!await fileExists(jsonPath)) {
     return { migrated: false, factCount: 0, reason: "no-legacy-json" };
   }
-  if (await fileExists(memoryMdPath(cwd))) {
+  if (await fileExists(memoryStore.memoryMdPath(cwd))) {
     process.stderr.write(
       `[theokit-sdk] memory migration skipped: both MEMORY.md and legacy JSON exist at ${jsonPath}; leaving both intact
 `
@@ -2458,7 +2379,7 @@ function createMemorySearchTool(opts) {
   };
 }
 function createMemoryGetTool(opts) {
-  const memoryRoot = path.resolve(memoryDir(opts.cwd));
+  const memoryRoot = path.resolve(memoryStore.memoryDir(opts.cwd));
   return {
     name: "memory_get",
     description: GET_DESCRIPTION,
@@ -2527,6 +2448,42 @@ function isPathInside(root, candidate) {
   return candidate === root || candidate.startsWith(normalizedRoot);
 }
 
+Object.defineProperty(exports, "appendFact", {
+  enumerable: true,
+  get: function () { return memoryStore.appendFact; }
+});
+Object.defineProperty(exports, "appendFactToMarkdown", {
+  enumerable: true,
+  get: function () { return memoryStore.appendFactToMarkdown; }
+});
+Object.defineProperty(exports, "claudeProjectMemoryDir", {
+  enumerable: true,
+  get: function () { return memoryStore.claudeProjectMemoryDir; }
+});
+Object.defineProperty(exports, "memoryDir", {
+  enumerable: true,
+  get: function () { return memoryStore.memoryDir; }
+});
+Object.defineProperty(exports, "memoryMdPath", {
+  enumerable: true,
+  get: function () { return memoryStore.memoryMdPath; }
+});
+Object.defineProperty(exports, "memoryWriteDir", {
+  enumerable: true,
+  get: function () { return memoryStore.memoryWriteDir; }
+});
+Object.defineProperty(exports, "notesDir", {
+  enumerable: true,
+  get: function () { return memoryStore.notesDir; }
+});
+Object.defineProperty(exports, "readFacts", {
+  enumerable: true,
+  get: function () { return memoryStore.readFacts; }
+});
+Object.defineProperty(exports, "readFactsFromMarkdown", {
+  enumerable: true,
+  get: function () { return memoryStore.readFactsFromMarkdown; }
+});
 Object.defineProperty(exports, "createOpenAiCompatibleRuntime", {
   enumerable: true,
   get: function () { return memoryAdapters.createOpenAiCompatibleRuntime; }
@@ -2555,8 +2512,6 @@ exports.PRAGMA_STATEMENTS = PRAGMA_STATEMENTS;
 exports.SCHEMA_STATEMENTS = SCHEMA_STATEMENTS;
 exports.VALID_BACKENDS = VALID_BACKENDS;
 exports.appendDiaryEntry = appendDiaryEntry;
-exports.appendFact = appendFact;
-exports.appendFactToMarkdown = appendFactToMarkdown;
 exports.assertValidBackend = assertValidBackend;
 exports.azureOpenAiMemoryEmbeddingProviderAdapter = azureOpenAiMemoryEmbeddingProviderAdapter;
 exports.buildErrorMetadata = buildErrorMetadata;
@@ -2587,12 +2542,9 @@ exports.lightPhase = lightPhase;
 exports.listNotes = listNotes;
 exports.loadSqliteVecExtension = loadSqliteVecExtension;
 exports.mapOpenAICompatibleError = mapOpenAICompatibleError;
-exports.memoryDir = memoryDir;
-exports.memoryMdPath = memoryMdPath;
 exports.migrateLegacyJson = migrateLegacyJson;
 exports.migrateSqliteToLance = migrateSqliteToLance;
 exports.mistralMemoryEmbeddingProviderAdapter = mistralMemoryEmbeddingProviderAdapter;
-exports.notesDir = notesDir;
 exports.ollamaMemoryEmbeddingProviderAdapter = ollamaMemoryEmbeddingProviderAdapter;
 exports.openAiMemoryEmbeddingProviderAdapter = openAiMemoryEmbeddingProviderAdapter;
 exports.openLanceIndex = openLanceIndex;
@@ -2603,8 +2555,6 @@ exports.parseRetryAfter = parseRetryAfter;
 exports.parseSearchOptions = parseSearchOptions;
 exports.persistActiveMemoryTranscript = persistActiveMemoryTranscript;
 exports.readEmbeddingIdentity = readEmbeddingIdentity;
-exports.readFacts = readFacts;
-exports.readFactsFromMarkdown = readFactsFromMarkdown;
 exports.readMemoryFileBounded = readMemoryFileBounded;
 exports.redactSecrets = redactSecrets;
 exports.remPhase = remPhase;