@memstack/core 0.7.2 → 0.8.0

package/dist/index.cjs

@@ -726,6 +726,7 @@ var MemoryStore = class {
 
 // src/adapters/storage/memory.ts
 var InMemoryStorageAdapter = class {
+  capabilities = { multiProcess: false };
   memories = /* @__PURE__ */ new Map();
   async initialize() {
   }
@@ -821,8 +822,10 @@ var InMemoryStorageAdapter = class {
         results.sort((a, b) => b.importance - a.importance || b._touchedAt.getTime() - a._touchedAt.getTime());
         break;
     }
-    for (const r of results.slice(0, query.limit ?? 10)) {
-      r._touchedAt = /* @__PURE__ */ new Date();
+    if (query.touch !== false) {
+      for (const r of results.slice(0, query.limit ?? 10)) {
+        r._touchedAt = /* @__PURE__ */ new Date();
+      }
     }
     const limit = query.limit ?? 10;
     return results.slice(0, limit);
@@ -854,6 +857,25 @@ var InMemoryStorageAdapter = class {
   }
 };
 
+// src/enrichment.ts
+var ENRICHMENT_MAX_TOKENS = 1024;
+function extractJson(text) {
+  let cleaned = text.trim();
+  const fenceMatch = cleaned.match(/```(?:json)?\s*([\s\S]*?)```/);
+  if (fenceMatch) cleaned = fenceMatch[1].trim();
+  return cleaned;
+}
+function parseTags(text, max = 5) {
+  try {
+    const parsed = JSON.parse(extractJson(text));
+    if (Array.isArray(parsed) && parsed.every((t) => typeof t === "string")) {
+      return parsed.map((t) => t.toLowerCase().trim()).slice(0, max);
+    }
+  } catch {
+  }
+  return text.split(",").map((t) => t.replace(/[\[\]"]/g, "").trim().toLowerCase()).filter((t) => t.length > 0).slice(0, max);
+}
+
 // src/client.ts
 var MemStack = class {
   memory;
@@ -886,7 +908,7 @@ var MemStack = class {
           const result = await this.config.llm.complete({
             system: 'Analyze the memory and respond with a JSON object: {"importance": <0.0-1.0>, "tags": [<array of 1-5 lowercase single-word tags>]}. Return ONLY the JSON, nothing else.',
             user: input.content,
-            maxTokens: 100,
+            maxTokens: ENRICHMENT_MAX_TOKENS,
             temperature: 0
           });
           const parsed = this._parseEnrichmentJson(result.text);
@@ -896,7 +918,7 @@ var MemStack = class {
           const result = await this.config.llm.complete({
             system: "Rate the importance of the following memory for an AI agent on a scale of 0.0 to 1.0, where 0.0 is trivial and 1.0 is critical. Return ONLY a single float number, nothing else.",
             user: input.content,
-            maxTokens: 10,
+            maxTokens: ENRICHMENT_MAX_TOKENS,
             temperature: 0
           });
           const parsed = parseFloat(result.text.trim());
@@ -905,10 +927,10 @@ var MemStack = class {
           const result = await this.config.llm.complete({
             system: 'Extract 1-5 concise, lowercase, single-word tags from the following memory. Return ONLY a JSON array of strings, nothing else. Example: ["combat", "goblin", "forest"]',
             user: input.content,
-            maxTokens: 80,
+            maxTokens: ENRICHMENT_MAX_TOKENS,
             temperature: 0
           });
-          tags = this._parseTagsJson(result.text);
+          tags = parseTags(result.text);
         }
       } catch (err) {
         this.config.hooks?.onError?.(
@@ -1026,7 +1048,7 @@ var MemStack = class {
   }
   _parseEnrichmentJson(text) {
     try {
-      const json = JSON.parse(this._extractJson(text));
+      const json = JSON.parse(extractJson(text));
       const result = {};
       if (typeof json.importance === "number" && Number.isFinite(json.importance)) {
         result.importance = Math.max(0, Math.min(1, json.importance));
@@ -1039,25 +1061,448 @@ var MemStack = class {
       return {};
     }
   }
-  _parseTagsJson(text) {
-    try {
-      const parsed = JSON.parse(this._extractJson(text));
-      if (Array.isArray(parsed) && parsed.every((t) => typeof t === "string")) {
-        return parsed.map((t) => t.toLowerCase().trim()).slice(0, 5);
+};
+
+// src/retrieval/text.ts
+var STOPWORDS = /* @__PURE__ */ new Set([
+  "a",
+  "an",
+  "and",
+  "are",
+  "as",
+  "at",
+  "be",
+  "by",
+  "did",
+  "do",
+  "does",
+  "for",
+  "from",
+  "how",
+  "i",
+  "in",
+  "is",
+  "it",
+  "its",
+  "me",
+  "my",
+  "of",
+  "on",
+  "or",
+  "our",
+  "that",
+  "the",
+  "this",
+  "to",
+  "was",
+  "we",
+  "were",
+  "what",
+  "when",
+  "where",
+  "which",
+  "who",
+  "why",
+  "with",
+  "you",
+  "your",
+  // Verbs that frame a question ("what do we use?") without saying what it is about.
+  "can",
+  "could",
+  "has",
+  "have",
+  "should",
+  "use",
+  "used",
+  "uses",
+  "using",
+  "would"
+]);
+function tokenize(text) {
+  return text.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [];
+}
+function queryTerms(text) {
+  const words = [...new Set(tokenize(text))];
+  const meaningful = words.filter((w) => !STOPWORDS.has(w));
+  return [...new Set((meaningful.length > 0 ? meaningful : words).map(stem))];
+}
+function documentTerms(text) {
+  return tokenize(text).map(stem);
+}
+var STEP2 = {
+  ational: "ate",
+  tional: "tion",
+  enci: "ence",
+  anci: "ance",
+  izer: "ize",
+  bli: "ble",
+  alli: "al",
+  entli: "ent",
+  eli: "e",
+  ousli: "ous",
+  ization: "ize",
+  ation: "ate",
+  ator: "ate",
+  alism: "al",
+  iveness: "ive",
+  fulness: "ful",
+  ousness: "ous",
+  aliti: "al",
+  iviti: "ive",
+  biliti: "ble",
+  logi: "log"
+};
+var STEP3 = {
+  icate: "ic",
+  ative: "",
+  alize: "al",
+  iciti: "ic",
+  ical: "ic",
+  ful: "",
+  ness: ""
+};
+var STEP4 = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/;
+var C = "[^aeiou]";
+var V = "[aeiouy]";
+var CS = `${C}[^aeiouy]*`;
+var VS = `${V}[aeiou]*`;
+var MGR0 = new RegExp(`^(${CS})?${VS}${CS}`);
+var MEQ1 = new RegExp(`^(${CS})?${VS}${CS}(${VS})?$`);
+var MGR1 = new RegExp(`^(${CS})?${VS}${CS}${VS}${CS}`);
+var HAS_VOWEL = new RegExp(`^(${CS})?${V}`);
+var CVC = new RegExp(`^${CS}${V}[^aeiouwxy]$`);
+function stem(word) {
+  if (word.length < 3 || !/^[a-z]+$/.test(word)) return word;
+  let w = word;
+  const firstY = w[0] === "y";
+  if (firstY) w = "Y" + w.slice(1);
+  if (/(ss|i)es$/.test(w)) w = w.slice(0, -2);
+  else if (/[^s]s$/.test(w)) w = w.slice(0, -1);
+  let m;
+  if (m = w.match(/^(.+?)eed$/)) {
+    if (MGR0.test(m[1])) w = w.slice(0, -1);
+  } else if (m = w.match(/^(.+?)(ed|ing)$/)) {
+    const base = m[1];
+    if (HAS_VOWEL.test(base)) {
+      w = base;
+      if (/(at|bl|iz)$/.test(w)) w += "e";
+      else if (/([^aeiouylsz])\1$/.test(w)) w = w.slice(0, -1);
+      else if (CVC.test(w)) w += "e";
+    }
+  }
+  if ((m = w.match(/^(.+?)y$/)) && HAS_VOWEL.test(m[1])) w = m[1] + "i";
+  if (m = w.match(/^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/)) {
+    if (MGR0.test(m[1])) w = m[1] + STEP2[m[2]];
+  }
+  if (m = w.match(/^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/)) {
+    if (MGR0.test(m[1])) w = m[1] + STEP3[m[2]];
+  }
+  if (m = w.match(STEP4)) {
+    if (MGR1.test(m[1])) w = m[1];
+  } else if (m = w.match(/^(.+?)(s|t)(ion)$/)) {
+    const base = m[1] + m[2];
+    if (MGR1.test(base)) w = base;
+  }
+  if (m = w.match(/^(.+?)e$/)) {
+    const base = m[1];
+    if (MGR1.test(base) || MEQ1.test(base) && !CVC.test(base)) w = base;
+  }
+  if (/ll$/.test(w) && MGR1.test(w)) w = w.slice(0, -1);
+  if (firstY) w = "y" + w.slice(1);
+  return w;
+}
+
+// src/retrieval/LexicalRetriever.ts
+var K1 = 1.2;
+var B = 0.75;
+var PREFIX_WEIGHT = 0.5;
+var MIN_PREFIX_LENGTH = 3;
+var LexicalRetriever = class {
+  constructor(storage, config = {}) {
+    this.storage = storage;
+    this.candidateLimit = config.candidateLimit ?? 2e3;
+    this.touch = config.touch ?? true;
+  }
+  storage;
+  candidateLimit;
+  touch;
+  async recall(query) {
+    const limit = query.limit ?? 10;
+    const maxChars = query.maxChars ?? 8e3;
+    const terms = queryTerms(query.query ?? "");
+    let ranked = [];
+    let candidates;
+    if (terms.length > 0 && this.storage.search && this.storage.capabilities?.textSearch) {
+      ranked = (await this.storage.search({
+        actorIds: query.actorIds,
+        query: query.query,
+        memoryTypes: query.memoryTypes,
+        limit: this.candidateLimit
+      })).map(({ memory, score }) => ({ memory, score }));
+    } else if (terms.length > 0) {
+      candidates = await this.loadCandidates(query);
+      ranked = rank(candidates, terms);
+    }
+    const fallback = ranked.length === 0;
+    if (fallback) {
+      candidates ??= await this.loadCandidates(query);
+      ranked = [...candidates].sort(byImportanceThenRecency).map((memory) => ({ memory, score: 0 }));
+    }
+    const hits = withinBudget(ranked, limit, maxChars);
+    if (this.touch) await this.touchAll(hits);
+    return { hits, fallback };
+  }
+  async loadCandidates(query) {
+    const byId = /* @__PURE__ */ new Map();
+    for (const actorId of new Set(query.actorIds)) {
+      const memories = await this.storage.retrieve({
+        actorId,
+        memoryTypes: query.memoryTypes,
+        limit: this.candidateLimit,
+        strategy: "important",
+        touch: false
+      });
+      for (const memory of memories) byId.set(memory.id, memory);
+    }
+    return [...byId.values()];
+  }
+  async touchAll(hits) {
+    if (!this.storage.touch) return;
+    await Promise.all(
+      hits.map(
+        ({ memory }) => this.storage.touch(memory.id).catch(() => {
+        })
+      )
+    );
+  }
+};
+function rank(memories, terms) {
+  if (memories.length === 0) return [];
+  const candidates = memories.map((memory) => {
+    const tokens = documentTerms(`${memory.content} ${memory.tags.join(" ")}`);
+    const counts = /* @__PURE__ */ new Map();
+    for (const token of tokens) counts.set(token, (counts.get(token) ?? 0) + 1);
+    return { memory, terms: counts, length: tokens.length };
+  });
+  const avgLength = candidates.reduce((sum, c) => sum + c.length, 0) / candidates.length || 1;
+  const n = candidates.length;
+  const frequencies = terms.map(
+    (term) => candidates.map((c) => {
+      let tf = c.terms.get(term) ?? 0;
+      if (term.length >= MIN_PREFIX_LENGTH) {
+        for (const [docTerm, count] of c.terms) {
+          if (docTerm !== term && docTerm.startsWith(term)) tf += count * PREFIX_WEIGHT;
+        }
       }
-    } catch {
+      return tf;
+    })
+  );
+  const hits = [];
+  candidates.forEach((c, i) => {
+    let score = 0;
+    frequencies.forEach((perCandidate) => {
+      const tf = perCandidate[i];
+      if (tf === 0) return;
+      const df = perCandidate.filter((f) => f > 0).length;
+      const idf = Math.log(1 + (n - df + 0.5) / (df + 0.5));
+      score += idf * (tf * (K1 + 1) / (tf + K1 * (1 - B + B * c.length / avgLength)));
+    });
+    if (score > 0) hits.push({ memory: c.memory, score });
+  });
+  return hits.sort((a, b) => b.score - a.score || byImportanceThenRecency(a.memory, b.memory));
+}
+function byImportanceThenRecency(a, b) {
+  return b.importance - a.importance || b.createdAt.getTime() - a.createdAt.getTime();
+}
+function withinBudget(ranked, limit, maxChars) {
+  const hits = [];
+  let chars = 0;
+  for (const hit of ranked) {
+    if (hits.length >= limit) break;
+    const size = hit.memory.content.length;
+    if (hits.length > 0 && chars + size > maxChars) continue;
+    hits.push(hit);
+    chars += size;
+  }
+  return hits;
+}
+
+// src/harness/namespaces.ts
+var GLOBAL_NAMESPACE = "global";
+function projectNamespace(projectId) {
+  if (!projectId) throw new Error("projectId is required");
+  return `project:${projectId}`;
+}
+function sessionNamespace(projectId, sessionId) {
+  if (!projectId || !sessionId) throw new Error("projectId and sessionId are required");
+  return `session:${projectId}:${sessionId}`;
+}
+function defaultRecallNamespaces(projectId) {
+  return [projectNamespace(projectId), GLOBAL_NAMESPACE];
+}
+
+// src/harness/HarnessMemory.ts
+var MAX_TAGS = 8;
+var TAG_PROMPT = 'You tag memories so they can be found later by keyword search. Return 3-5 lowercase, single-word topic tags as a JSON array of strings, and nothing else. Include broader category words a person might search for, not only words already in the text. Example: for "This project uses Hono" return ["framework", "backend", "web", "server", "hono"].';
+var HarnessMemory = class {
+  storage;
+  llm;
+  retriever;
+  autoTags;
+  tagTimeoutMs;
+  maxContentChars;
+  onError;
+  initialized;
+  constructor(config) {
+    this.storage = config.storage;
+    this.llm = config.llm;
+    this.retriever = new LexicalRetriever(config.storage, { candidateLimit: config.candidateLimit });
+    this.autoTags = config.autoTags ?? true;
+    this.tagTimeoutMs = config.tagTimeoutMs ?? 1e4;
+    this.maxContentChars = config.maxContentChars ?? 8e3;
+    this.onError = config.onError;
+  }
+  async remember(input) {
+    const content = input.content.trim();
+    if (!content) throw validationError("Memory content is empty");
+    if (content.length > this.maxContentChars) {
+      throw validationError(`Memory content is longer than ${this.maxContentChars} characters`, {
+        length: content.length
+      });
+    }
+    if (!input.namespace) throw validationError("Namespace is required");
+    if (input.importance !== void 0 && !(input.importance >= 0 && input.importance <= 1)) {
+      throw validationError("Importance must be between 0 and 1", { importance: input.importance });
+    }
+    await this.ensureInit();
+    const llmTags = this.autoTags ? await this.suggestTags(content) : [];
+    const tags = [...new Set([...input.tags ?? [], ...llmTags].map((t) => t.toLowerCase().trim()).filter(Boolean))];
+    return this.storage.store({
+      actorId: input.namespace,
+      content,
+      memoryType: input.kind ?? "observation",
+      importance: input.importance ?? 0.5,
+      tags: tags.slice(0, MAX_TAGS),
+      metadata: { source: input.source }
+    });
+  }
+  async recall(input) {
+    await this.ensureInit();
+    return this.retriever.recall({
+      actorIds: input.namespaces,
+      query: input.query,
+      memoryTypes: input.kinds,
+      limit: input.limit,
+      maxChars: input.maxChars
+    });
+  }
+  /** The memory with this ID, or null when it does not exist or is outside `namespaces`. */
+  async get(id, namespaces) {
+    await this.ensureInit();
+    const memory = await this.storage.get(id);
+    return memory && namespaces.includes(memory.actorId) ? memory : null;
+  }
+  /** Delete a memory. Memories outside `namespaces` are reported as not found. */
+  async forget(id, namespaces) {
+    const memory = await this.get(id, namespaces);
+    if (!memory) throw notFound("Memory", id);
+    await this.storage.delete(id);
+  }
+  /** Number of memories in each namespace. */
+  async stats(namespaces) {
+    await this.ensureInit();
+    const counts = {};
+    for (const namespace of new Set(namespaces)) {
+      counts[namespace] = await this.storage.count({ actorId: namespace });
+    }
+    return counts;
+  }
+  /**
+   * Moves every memory from one namespace to another, keeping content,
+   * kind, importance, tags, provenance, and creation time. Memories get new
+   * IDs. Used when a project's ID changes, e.g. after its first commit.
+   * Safe to run from two processes at once: a copy whose original was
+   * already moved by the other process is removed again.
+   */
+  async moveNamespace(from, to) {
+    if (!from || !to) throw validationError("Both namespaces are required");
+    if (from === to) return 0;
+    await this.ensureInit();
+    let moved = 0;
+    for (; ; ) {
+      const batch = await this.storage.retrieve({ actorId: from, limit: 500, strategy: "recent", touch: false });
+      if (batch.length === 0) return moved;
+      let progressed = false;
+      for (const memory of batch) {
+        const copy = await this.storage.store({
+          actorId: to,
+          content: memory.content,
+          memoryType: memory.memoryType,
+          importance: memory.importance,
+          emotionalValence: memory.emotionalValence,
+          tags: memory.tags,
+          metadata: memory.metadata,
+          createdAt: memory.createdAt,
+          expiresAt: memory.expiresAt
+        });
+        try {
+          await this.storage.delete(memory.id);
+          moved++;
+          progressed = true;
+        } catch (error) {
+          await this.storage.delete(copy.id);
+          if (!(error instanceof MemStackError && error.code === "NOT_FOUND")) throw error;
+        }
+      }
+      if (!progressed) return moved;
     }
-    return text.split(",").map((t) => t.replace(/[\[\]"]/g, "").trim().toLowerCase()).filter((t) => t.length > 0).slice(0, 5);
   }
-  /** Strip markdown code fences and extract the JSON payload from LLM output. */
-  _extractJson(text) {
-    let cleaned = text.trim();
-    const fenceMatch = cleaned.match(/```(?:json)?\s*([\s\S]*?)```/);
-    if (fenceMatch) cleaned = fenceMatch[1].trim();
-    return cleaned;
+  /**
+   * Adopts memories a project stored under IDs it had before, such as
+   * before its first commit. Costs one count per previous ID when there is
+   * nothing to move. Returns the number of memories moved.
+   */
+  async adoptProjects(previousIds, projectId) {
+    const target = projectNamespace(projectId);
+    let moved = 0;
+    for (const id of new Set(previousIds)) {
+      const from = projectNamespace(id);
+      if (from === target) continue;
+      await this.ensureInit();
+      if (await this.storage.count({ actorId: from }) === 0) continue;
+      moved += await this.moveNamespace(from, target);
+    }
+    return moved;
+  }
+  ensureInit() {
+    this.initialized ??= this.storage.initialize().catch((error) => {
+      this.initialized = void 0;
+      throw error;
+    });
+    return this.initialized;
+  }
+  async suggestTags(content) {
+    let timer;
+    try {
+      const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`Tagging timed out after ${this.tagTimeoutMs} ms`)), this.tagTimeoutMs);
+      });
+      const result = await Promise.race([
+        this.llm.complete({ system: TAG_PROMPT, user: content, maxTokens: ENRICHMENT_MAX_TOKENS, temperature: 0 }),
+        timeout
+      ]);
+      if (!result.text.trim()) throw new Error("Tagging returned an empty reply");
+      return parseTags(result.text).filter((t) => /^[\p{L}\p{N}-]+$/u.test(t));
+    } catch (error) {
+      this.onError?.(error instanceof Error ? error : new Error(String(error)), "harness-tagging");
+      return [];
+    } finally {
+      clearTimeout(timer);
+    }
   }
 };
 var DiskStorageAdapter = class {
+  capabilities = { multiProcess: false };
   dir;
   _writeLocks = /* @__PURE__ */ new Map();
   _idIndex = /* @__PURE__ */ new Map();
@@ -1248,26 +1693,28 @@ var DiskStorageAdapter = class {
         );
         break;
     }
-    const nowStr = (/* @__PURE__ */ new Date()).toISOString();
-    const toTouch = results.slice(0, query.limit ?? 10);
-    const touchedActors = /* @__PURE__ */ new Set();
-    for (const r of toTouch) {
-      r._touchedAt = nowStr;
-      touchedActors.add(r.actorId);
-    }
-    for (const actorId of touchedActors) {
-      await this._withWriteLock(actorId, async () => {
-        const records = await this._readFile(actorId);
-        let changed = false;
-        for (const r of records) {
-          const touched = toTouch.find((t) => t.id === r.id);
-          if (touched) {
-            r._touchedAt = nowStr;
-            changed = true;
+    if (query.touch !== false) {
+      const nowStr = (/* @__PURE__ */ new Date()).toISOString();
+      const toTouch = results.slice(0, query.limit ?? 10);
+      const touchedActors = /* @__PURE__ */ new Set();
+      for (const r of toTouch) {
+        r._touchedAt = nowStr;
+        touchedActors.add(r.actorId);
+      }
+      for (const actorId of touchedActors) {
+        await this._withWriteLock(actorId, async () => {
+          const records = await this._readFile(actorId);
+          let changed = false;
+          for (const r of records) {
+            const touched = toTouch.find((t) => t.id === r.id);
+            if (touched) {
+              r._touchedAt = nowStr;
+              changed = true;
+            }
           }
-        }
-        if (changed) await this._writeFile(actorId, records);
-      });
+          if (changed) await this._writeFile(actorId, records);
+        });
+      }
     }
     const limit = query.limit ?? 10;
     return results.slice(0, limit).map((r) => this._toExternal(r));
@@ -1418,6 +1865,7 @@ var DiskStorageAdapter = class {
   }
 };
 var MarkdownStorageAdapter = class {
+  capabilities = { multiProcess: false };
   dir;
   oneFilePerActor;
   _cache = null;
@@ -1934,6 +2382,7 @@ var HybridStorageAdapter = class {
 
 // src/adapters/storage/postgres.ts
 var PostgresStorageAdapter = class {
+  capabilities = { multiProcess: true };
   pool;
   table;
   vectorDimensions;
@@ -1969,7 +2418,8 @@ var PostgresStorageAdapter = class {
     const connStr = this._connectionString ?? this._buildConnString();
     try {
       const { default: createPostgres } = await import('postgres');
-      const options = {};
+      const options = { onnotice: () => {
+      } };
       if (this._ssl) {
         options.ssl = typeof this._ssl === "object" ? this._ssl : "require";
       }
@@ -2002,35 +2452,50 @@ var PostgresStorageAdapter = class {
     }
     return connStr;
   }
+  // One DO block, so it runs in a single transaction on one connection: the
+  // advisory lock makes processes that start together (Claude Code and Codex)
+  // migrate one at a time instead of racing on CREATE ... IF NOT EXISTS,
+  // which Postgres reports as a duplicate key in pg_type.
   async _runMigration() {
-    try {
-      await this.pool.query("CREATE EXTENSION IF NOT EXISTS vector");
-    } catch {
-    }
     await this.pool.query(`
-      CREATE TABLE IF NOT EXISTS ${this.table} (
-        id TEXT PRIMARY KEY,
-        actor_id TEXT NOT NULL,
-        memory_type TEXT NOT NULL DEFAULT 'interaction',
-        content TEXT NOT NULL,
-        importance REAL NOT NULL DEFAULT 0.5,
-        emotional_valence REAL NOT NULL DEFAULT 0,
-        tags JSONB NOT NULL DEFAULT '[]',
-        embedding vector(${this.vectorDimensions}),
-        source_id TEXT,
-        metadata JSONB NOT NULL DEFAULT '{}',
-        expires_at TIMESTAMPTZ,
-        created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-        touched_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
-      )
+      DO $memstack$
+      BEGIN
+        PERFORM pg_advisory_xact_lock(hashtext('memstack:migrate:${this.table}'));
+        BEGIN
+          CREATE EXTENSION IF NOT EXISTS vector;
+        EXCEPTION WHEN OTHERS THEN
+          NULL; -- pgvector may not be available
+        END;
+        CREATE TABLE IF NOT EXISTS ${this.table} (
+          id TEXT PRIMARY KEY,
+          actor_id TEXT NOT NULL,
+          memory_type TEXT NOT NULL DEFAULT 'interaction',
+          content TEXT NOT NULL,
+          importance REAL NOT NULL DEFAULT 0.5,
+          emotional_valence REAL NOT NULL DEFAULT 0,
+          tags JSONB NOT NULL DEFAULT '[]',
+          embedding vector(${this.vectorDimensions}),
+          source_id TEXT,
+          metadata JSONB NOT NULL DEFAULT '{}',
+          expires_at TIMESTAMPTZ,
+          created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+          touched_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+        );
+        BEGIN
+          CREATE INDEX IF NOT EXISTS idx_${this.table}_actor ON ${this.table} (actor_id);
+          CREATE INDEX IF NOT EXISTS idx_${this.table}_created ON ${this.table} (created_at DESC);
+          CREATE INDEX IF NOT EXISTS idx_${this.table}_importance ON ${this.table} (importance DESC);
+        EXCEPTION WHEN OTHERS THEN
+          NULL; -- index creation may fail; non-critical
+        END;
+        BEGIN
+          CREATE INDEX IF NOT EXISTS idx_${this.table}_embedding ON ${this.table} USING hnsw (embedding vector_cosine_ops) WITH (m = 16, ef_construction = 64);
+        EXCEPTION WHEN OTHERS THEN
+          NULL; -- index creation may fail; non-critical
+        END;
+      END
+      $memstack$
     `);
-    try {
-      await this.pool.query(`CREATE INDEX IF NOT EXISTS idx_${this.table}_actor ON ${this.table} (actor_id)`);
-      await this.pool.query(`CREATE INDEX IF NOT EXISTS idx_${this.table}_created ON ${this.table} (created_at DESC)`);
-      await this.pool.query(`CREATE INDEX IF NOT EXISTS idx_${this.table}_importance ON ${this.table} (importance DESC)`);
-      await this.pool.query(`CREATE INDEX IF NOT EXISTS idx_${this.table}_embedding ON ${this.table} USING hnsw (embedding vector_cosine_ops) WITH (m = 16, ef_construction = 64)`);
-    } catch {
-    }
   }
   generateId() {
     return `mem_${Date.now().toString(36)}_${crypto.randomUUID().slice(0, 8)}`;
@@ -2165,9 +2630,11 @@ var PostgresStorageAdapter = class {
     const sql = `SELECT * FROM ${this.table} ${where} ORDER BY ${orderBy} LIMIT $${paramIdx}`;
     params.push(limit);
     const { rows } = await this.pool.query(sql, params);
-    for (const row of rows.slice(0, limit)) {
-      const r = row;
-      await this.pool.query(`UPDATE ${this.table} SET touched_at = NOW() WHERE id = $1`, [r.id]);
+    if (query.touch !== false) {
+      for (const row of rows.slice(0, limit)) {
+        const r = row;
+        await this.pool.query(`UPDATE ${this.table} SET touched_at = NOW() WHERE id = $1`, [r.id]);
+      }
     }
     return rows.map((r) => this._rowToMemory(r));
   }
@@ -2231,9 +2698,11 @@ var PostgresStorageAdapter = class {
     params.push(embedding);
     params.push(limit);
     const { rows } = await this.pool.query(sql, params);
-    for (const row of rows.slice(0, limit)) {
-      const r = row;
-      await this.pool.query(`UPDATE ${this.table} SET touched_at = NOW() WHERE id = $1`, [r.id]);
+    if (query.touch !== false) {
+      for (const row of rows.slice(0, limit)) {
+        const r = row;
+        await this.pool.query(`UPDATE ${this.table} SET touched_at = NOW() WHERE id = $1`, [r.id]);
+      }
     }
     return rows.map((r) => this._rowToMemory(r));
   }
@@ -2257,6 +2726,7 @@ var PostgresStorageAdapter = class {
 
 // src/adapters/storage/redis.ts
 var RedisStorageAdapter = class {
+  capabilities = { multiProcess: true };
   redis;
   prefix;
   constructor(config) {
@@ -2394,11 +2864,13 @@ var RedisStorageAdapter = class {
         );
         break;
     }
-    const nowStr = (/* @__PURE__ */ new Date()).toISOString();
-    const toTouch = results.slice(0, query.limit ?? 10);
-    for (const r of toTouch) {
-      r._touchedAt = nowStr;
-      await this.redis.set(this._memKey(r.id), JSON.stringify(r));
+    if (query.touch !== false) {
+      const nowStr = (/* @__PURE__ */ new Date()).toISOString();
+      const toTouch = results.slice(0, query.limit ?? 10);
+      for (const r of toTouch) {
+        r._touchedAt = nowStr;
+        await this.redis.set(this._memKey(r.id), JSON.stringify(r));
+      }
     }
     const limit = query.limit ?? 10;
     return results.slice(0, limit).map((r) => this._toExternal(r));
@@ -3332,6 +3804,7 @@ var LanceDBStorageAdapter = class {
 
 // src/adapters/storage/mongodb.ts
 var MongoDBStorageAdapter = class {
+  capabilities = { multiProcess: true };
   collection;
   vectorDimensions;
   constructor(config) {
@@ -3380,7 +3853,16 @@ var MongoDBStorageAdapter = class {
       expiresAt: input.expiresAt,
       createdAt: input.createdAt ?? now
     };
-    await this.collection.insertOne(this.toDoc(memory));
+    if (input.id) {
+      const { _id, actorId, memoryType, createdAt, ...fields } = this.toDoc(memory);
+      await this.collection.updateOne(
+        { _id },
+        { $set: fields, $setOnInsert: { actorId, memoryType, createdAt } },
+        { upsert: true }
+      );
+    } else {
+      await this.collection.insertOne(this.toDoc(memory));
+    }
     return memory;
   }
   async storeBatch(inputs) {
@@ -3510,6 +3992,33 @@ var MongoDBStorageAdapter = class {
 };
 
 // src/adapters/storage/sqlite.ts
+var MIGRATIONS_TABLE = "memstack_schema_migrations";
+var MIGRATIONS = [
+  {
+    version: 1,
+    sql: (t) => `
+      CREATE TABLE IF NOT EXISTS ${t} (
+        id TEXT PRIMARY KEY,
+        actor_id TEXT NOT NULL,
+        memory_type TEXT NOT NULL DEFAULT 'interaction',
+        content TEXT NOT NULL,
+        importance REAL NOT NULL DEFAULT 0.5,
+        emotional_valence REAL NOT NULL DEFAULT 0,
+        tags TEXT NOT NULL DEFAULT '[]',
+        embedding TEXT,
+        source_id TEXT,
+        metadata TEXT NOT NULL DEFAULT '{}',
+        expires_at TEXT,
+        created_at TEXT NOT NULL,
+        touched_at TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_${t}_actor ON ${t}(actor_id);
+      CREATE INDEX IF NOT EXISTS idx_${t}_created ON ${t}(created_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_${t}_importance ON ${t}(importance DESC);
+    `
+  }
+];
+MIGRATIONS[MIGRATIONS.length - 1].version;
 function cosineSimilarity(a, b) {
   if (a.length === 0 || b.length === 0) return 0;
   const dims = Math.min(a.length, b.length);
@@ -3525,9 +4034,12 @@ function cosineSimilarity(a, b) {
   return mag === 0 ? 0 : dot / mag;
 }
 var SQLiteStorageAdapter = class {
+  capabilities = { multiProcess: true };
   db;
   table;
   vectorDimensions;
+  busyTimeoutMs;
+  walMode;
   constructor(config) {
     if (!config.db) {
       throw configError("SQLiteStorageAdapter requires a better-sqlite3 database instance");
@@ -3538,33 +4050,67 @@ var SQLiteStorageAdapter = class {
       throw configError(`Invalid table name: "${this.table}". Use only alphanumeric characters and underscores.`);
     }
     this.vectorDimensions = config.vectorDimensions ?? 1536;
+    this.busyTimeoutMs = config.busyTimeoutMs ?? 5e3;
+    if (!Number.isInteger(this.busyTimeoutMs) || this.busyTimeoutMs < 0) {
+      throw configError(`Invalid busyTimeoutMs: ${config.busyTimeoutMs}. Use a non-negative integer.`);
+    }
+    this.walMode = config.walMode ?? true;
   }
   async initialize() {
-    this.db.exec(`
-      CREATE TABLE IF NOT EXISTS ${this.table} (
-        id TEXT PRIMARY KEY,
-        actor_id TEXT NOT NULL,
-        memory_type TEXT NOT NULL DEFAULT 'interaction',
-        content TEXT NOT NULL,
-        importance REAL NOT NULL DEFAULT 0.5,
-        emotional_valence REAL NOT NULL DEFAULT 0,
-        tags TEXT NOT NULL DEFAULT '[]',
-        embedding TEXT,
-        source_id TEXT,
-        metadata TEXT NOT NULL DEFAULT '{}',
-        expires_at TEXT,
-        created_at TEXT NOT NULL,
-        touched_at TEXT NOT NULL
-      )
-    `);
-    this.db.exec(`CREATE INDEX IF NOT EXISTS idx_${this.table}_actor ON ${this.table}(actor_id)`);
-    this.db.exec(`CREATE INDEX IF NOT EXISTS idx_${this.table}_created ON ${this.table}(created_at DESC)`);
-    this.db.exec(`CREATE INDEX IF NOT EXISTS idx_${this.table}_importance ON ${this.table}(importance DESC)`);
+    this.db.exec(`PRAGMA busy_timeout = ${this.busyTimeoutMs}`);
+    if (this.walMode) this.db.exec("PRAGMA journal_mode = WAL");
+    this.migrate();
+  }
+  /** Schema version applied to this adapter's table, 0 if none. */
+  schemaVersion() {
+    const row = this.db.prepare(
+      `SELECT version FROM ${MIGRATIONS_TABLE} WHERE table_name = ?`
+    ).get(this.table);
+    return row?.version ?? 0;
+  }
+  // Versions are tracked per table rather than with PRAGMA user_version,
+  // so adapters with different table names can share one database file.
+  migrate() {
+    for (const migration of MIGRATIONS) {
+      this.transaction(() => {
+        this.db.exec(
+          `CREATE TABLE IF NOT EXISTS ${MIGRATIONS_TABLE} (table_name TEXT PRIMARY KEY, version INTEGER NOT NULL)`
+        );
+        if (this.schemaVersion() >= migration.version) return;
+        this.db.exec(migration.sql(this.table));
+        this.db.prepare(
+          `INSERT INTO ${MIGRATIONS_TABLE} (table_name, version) VALUES (?, ?)
+           ON CONFLICT(table_name) DO UPDATE SET version = excluded.version`
+        ).run(this.table, migration.version);
+      });
+    }
+  }
+  // BEGIN IMMEDIATE takes the write lock up front, so a concurrent writer
+  // waits on busy_timeout instead of failing when it upgrades a read lock.
+  transaction(fn) {
+    if (this.db.inTransaction) return fn();
+    this.db.exec("BEGIN IMMEDIATE");
+    try {
+      const result = fn();
+      this.db.exec("COMMIT");
+      return result;
+    } catch (error) {
+      if (this.db.inTransaction !== false) {
+        try {
+          this.db.exec("ROLLBACK");
+        } catch {
+        }
+      }
+      throw error;
+    }
   }
   generateId() {
     return `mem_${Date.now().toString(36)}_${crypto.randomUUID().slice(0, 8)}`;
   }
   async store(input) {
+    return this.insert(input);
+  }
+  insert(input) {
     const now = (/* @__PURE__ */ new Date()).toISOString();
     const id = input.id ?? this.generateId();
     this.db.prepare(
@@ -3611,11 +4157,7 @@ var SQLiteStorageAdapter = class {
     };
   }
   async storeBatch(inputs) {
-    const results = [];
-    for (const input of inputs) {
-      results.push(await this.store(input));
-    }
-    return results;
+    return this.transaction(() => inputs.map((input) => this.insert(input)));
   }
   async get(id) {
     const row = this.db.prepare(
@@ -3661,7 +4203,6 @@ var SQLiteStorageAdapter = class {
       conditions.push("created_at <= ?");
       params.push(query.createdBefore.toISOString());
     }
-    const where = `WHERE ${conditions.join(" AND ")}`;
     const hasSemantic = (query.strategy === "semantic" || query.strategy === "hybrid") && embedding && embedding.length > 0;
     let orderBy;
     switch (query.strategy) {
@@ -3682,9 +4223,8 @@ var SQLiteStorageAdapter = class {
         break;
     }
     const limit = query.limit ?? 10;
-    const sql = `SELECT * FROM ${this.table} ${where} ORDER BY ${orderBy}`;
-    const rows = this.db.prepare(sql).all(...params);
-    let results = rows;
+    const sql = `SELECT * FROM ${this.table} WHERE ${conditions.join(" AND ")} ORDER BY ${orderBy}`;
+    let results = this.db.prepare(sql).all(...params);
     if (query.query) {
       const q = query.query.toLowerCase();
       results = results.filter((r) => r.content.toLowerCase().includes(q));
@@ -3704,17 +4244,12 @@ var SQLiteStorageAdapter = class {
       if (query.strategy === "hybrid") {
         scored.sort((a, b) => b.score + b.row.importance - (a.score + a.row.importance));
       }
-      const topK = scored.slice(0, limit);
-      for (const { row } of topK) {
-        this.db.prepare(`UPDATE ${this.table} SET touched_at = ? WHERE id = ?`).run((/* @__PURE__ */ new Date()).toISOString(), row.id);
-      }
-      return topK.map(({ row }) => this._rowToMemory(row));
+      const topK = scored.slice(0, limit).map(({ row }) => row);
+      this.touchRows(topK, query.touch);
+      return topK.map((row) => this._rowToMemory(row));
     }
-    const now = (/* @__PURE__ */ new Date()).toISOString();
     const limited = results.slice(0, limit);
-    for (const row of limited) {
-      this.db.prepare(`UPDATE ${this.table} SET touched_at = ? WHERE id = ?`).run(now, row.id);
-    }
+    this.touchRows(limited, query.touch);
     return limited.map((r) => this._rowToMemory(r));
   }
   async count(filter) {
@@ -3749,6 +4284,14 @@ var SQLiteStorageAdapter = class {
   async close() {
     this.db.close();
   }
+  touchRows(rows, touch) {
+    if (touch === false || rows.length === 0) return;
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const stmt = this.db.prepare(`UPDATE ${this.table} SET touched_at = ? WHERE id = ?`);
+    this.transaction(() => {
+      for (const row of rows) stmt.run(now, row.id);
+    });
+  }
   _rowToMemory(row) {
     return {
       id: row.id,
@@ -4257,10 +4800,13 @@ var GroqLLMAdapter = class {
 exports.AnthropicLLMAdapter = AnthropicLLMAdapter;
 exports.CohereEmbeddingAdapter = CohereEmbeddingAdapter;
 exports.DiskStorageAdapter = DiskStorageAdapter;
+exports.GLOBAL_NAMESPACE = GLOBAL_NAMESPACE;
 exports.GroqLLMAdapter = GroqLLMAdapter;
+exports.HarnessMemory = HarnessMemory;
 exports.HybridStorageAdapter = HybridStorageAdapter;
 exports.InMemoryStorageAdapter = InMemoryStorageAdapter;
 exports.LanceDBStorageAdapter = LanceDBStorageAdapter;
+exports.LexicalRetriever = LexicalRetriever;
 exports.MarkdownStorageAdapter = MarkdownStorageAdapter;
 exports.MemStack = MemStack;
 exports.MemStackError = MemStackError;
@@ -4275,7 +4821,10 @@ exports.RedisStorageAdapter = RedisStorageAdapter;
 exports.SQLiteStorageAdapter = SQLiteStorageAdapter;
 exports.WeaviateStorageAdapter = WeaviateStorageAdapter;
 exports.configError = configError;
+exports.defaultRecallNamespaces = defaultRecallNamespaces;
 exports.notFound = notFound;
+exports.projectNamespace = projectNamespace;
+exports.sessionNamespace = sessionNamespace;
 exports.storageError = storageError;
 exports.validationError = validationError;
 //# sourceMappingURL=index.cjs.map