@memstack/core 0.5.0 → 0.7.0

package/dist/index.d.cts

@@ -64,6 +64,7 @@ interface MemoryStoreInput {
     sourceId?: string;
     metadata?: Record<string, unknown>;
     expiresAt?: Date;
+    createdAt?: Date;
     onConflict?: "append";
     /** Pre-assigned ID. When set, the storage adapter uses it instead of generating one. */
     id?: string;
@@ -106,6 +107,7 @@ interface SummarizeOptions {
 }
 interface PruneStrategy {
     type: "byAge" | "byImportance" | "byCount" | "byType" | "custom" | "compose";
+    actorId?: string;
     maxAge?: number;
     minImportance?: number;
     maxPerActor?: number;
@@ -333,6 +335,13 @@ declare class DiskStorageAdapter implements StorageProvider {
     private _readFile;
     private _writeFile;
     private _withWriteLock;
+    /**
+     * Acquires an exclusive cross-process lock for `actorId` via `open(path, "wx")`
+     * (atomic create-if-absent). Retries with jittered backoff while the lock is
+     * held elsewhere, and steals locks left behind by a crashed process once
+     * they're older than `staleMs`.
+     */
+    private _acquireFileLock;
     private _listActors;
     private _buildIndex;
     private _toExternal;

package/dist/index.d.ts

@@ -64,6 +64,7 @@ interface MemoryStoreInput {
     sourceId?: string;
     metadata?: Record<string, unknown>;
     expiresAt?: Date;
+    createdAt?: Date;
     onConflict?: "append";
     /** Pre-assigned ID. When set, the storage adapter uses it instead of generating one. */
     id?: string;
@@ -106,6 +107,7 @@ interface SummarizeOptions {
 }
 interface PruneStrategy {
     type: "byAge" | "byImportance" | "byCount" | "byType" | "custom" | "compose";
+    actorId?: string;
     maxAge?: number;
     minImportance?: number;
     maxPerActor?: number;
@@ -333,6 +335,13 @@ declare class DiskStorageAdapter implements StorageProvider {
     private _readFile;
     private _writeFile;
     private _withWriteLock;
+    /**
+     * Acquires an exclusive cross-process lock for `actorId` via `open(path, "wx")`
+     * (atomic create-if-absent). Retries with jittered backoff while the lock is
+     * held elsewhere, and steals locks left behind by a crashed process once
+     * they're older than `staleMs`.
+     */
+    private _acquireFileLock;
     private _listActors;
     private _buildIndex;
     private _toExternal;

package/dist/index.js

@@ -1,4 +1,4 @@
-import { mkdir, readFile, writeFile, readdir, appendFile } from 'fs/promises';
+import { mkdir, readFile, writeFile, rename, unlink, open, stat, readdir, appendFile } from 'fs/promises';
 import { join } from 'path';
 
 // src/errors.ts
@@ -598,7 +598,7 @@ var MemoryStore = class {
   }
   async prune(strategy) {
     await this._ensureInit();
-    const allMemories = await this.storage.retrieve({ limit: this.limits.pruneScan });
+    const allMemories = await this.storage.retrieve({ actorId: strategy.actorId, limit: this.limits.pruneScan });
     const kept = this.pruner.execute(allMemories, strategy);
     const keptIds = new Set(kept.map((k) => k.id));
     const prunedIds = allMemories.filter((m) => !keptIds.has(m.id)).map((m) => m.id);
@@ -610,7 +610,7 @@ var MemoryStore = class {
   }
   async dryRunPrune(strategy) {
     await this._ensureInit();
-    const allMemories = await this.storage.retrieve({ limit: this.limits.pruneScan });
+    const allMemories = await this.storage.retrieve({ actorId: strategy.actorId, limit: this.limits.pruneScan });
     const kept = this.pruner.execute(allMemories, strategy);
     const keptIds = new Set(kept.map((k) => k.id));
     const wouldPrune = allMemories.filter((m) => !keptIds.has(m.id)).map((m) => m.id);
@@ -744,7 +744,7 @@ var InMemoryStorageAdapter = class {
       sourceId: input.sourceId,
       metadata: input.metadata ?? {},
       expiresAt: input.expiresAt,
-      createdAt: now,
+      createdAt: input.createdAt ?? now,
       _touchedAt: now
     };
     this.memories.set(memory.id, memory);
@@ -794,8 +794,11 @@ var InMemoryStorageAdapter = class {
       results = results.filter((m) => m.tags?.some((t) => query.tags.includes(t)));
     }
     if (query.query) {
-      const q = query.query.toLowerCase();
-      results = results.filter((m) => m.content.toLowerCase().includes(q));
+      const terms = query.query.toLowerCase().split(/\s+/).filter(Boolean);
+      results = results.filter((m) => {
+        const content = m.content.toLowerCase();
+        return terms.some((t) => content.includes(t));
+      });
     }
     if (query.createdAfter) {
       results = results.filter((m) => m.createdAt >= query.createdAfter);
@@ -981,7 +984,19 @@ var MemStack = class {
     if (snapshot.version !== 1) {
       throw validationError(`Unsupported snapshot version: ${snapshot.version}`);
     }
-    await this.memory.storeBatch(snapshot.memories);
+    const memories = snapshot.memories.map((m, i) => {
+      const createdAt = typeof m.createdAt === "string" ? new Date(m.createdAt) : m.createdAt;
+      const expiresAt = typeof m.expiresAt === "string" ? new Date(m.expiresAt) : m.expiresAt;
+      const label = m.id ? `id: ${m.id}` : `index ${i}`;
+      if (createdAt && isNaN(createdAt.getTime())) {
+        throw validationError(`Invalid createdAt for memory (${label}): ${String(m.createdAt)}`);
+      }
+      if (expiresAt && isNaN(expiresAt.getTime())) {
+        throw validationError(`Invalid expiresAt for memory (${label}): ${String(m.expiresAt)}`);
+      }
+      return { ...m, createdAt, expiresAt };
+    });
+    await this.memory.storeBatch(memories);
   }
   async health() {
     const status = { storage: false, llm: false, embedding: false };
@@ -1068,7 +1083,7 @@ var DiskStorageAdapter = class {
       sourceId: input.sourceId,
       metadata: input.metadata ?? {},
       expiresAt: input.expiresAt,
-      createdAt: now,
+      createdAt: input.createdAt ?? now,
       _touchedAt: now.toISOString()
     };
     await this._withWriteLock(input.actorId, async () => {
@@ -1101,7 +1116,7 @@ var DiskStorageAdapter = class {
         sourceId: input.sourceId,
         metadata: input.metadata ?? {},
         expiresAt: input.expiresAt,
-        createdAt: now,
+        createdAt: input.createdAt ?? now,
         _touchedAt: now.toISOString()
       };
       all.push(memory);
@@ -1208,8 +1223,11 @@ var DiskStorageAdapter = class {
         records = records.filter((r) => r.tags?.some((t) => query.tags.includes(t)));
       }
       if (query.query) {
-        const q = query.query.toLowerCase();
-        records = records.filter((r) => r.content.toLowerCase().includes(q));
+        const terms = query.query.toLowerCase().split(/\s+/).filter(Boolean);
+        records = records.filter((r) => {
+          const content = r.content.toLowerCase();
+          return terms.some((t) => content.includes(t));
+        });
       }
       results.push(...records);
     }
@@ -1300,9 +1318,14 @@ var DiskStorageAdapter = class {
     }
   }
   async _writeFile(actorId, records) {
+    const filePath = this._filePath(actorId);
+    const tmpPath = `${filePath}.${process.pid}.${Date.now().toString(36)}.tmp`;
     try {
-      await writeFile(this._filePath(actorId), JSON.stringify(records, null, 2), "utf-8");
+      await writeFile(tmpPath, JSON.stringify(records, null, 2), "utf-8");
+      await rename(tmpPath, filePath);
     } catch (err) {
+      await unlink(tmpPath).catch(() => {
+      });
       throw storageError(`Failed to write memories for actor ${actorId}: ${err.message}`);
     }
   }
@@ -1314,15 +1337,57 @@ var DiskStorageAdapter = class {
     });
     this._writeLocks.set(actorId, next);
     await prev;
+    const releaseFileLock = await this._acquireFileLock(actorId);
     try {
       await fn();
     } finally {
+      await releaseFileLock();
       resolve();
       if (this._writeLocks.get(actorId) === next) {
         this._writeLocks.delete(actorId);
       }
     }
   }
+  /**
+   * Acquires an exclusive cross-process lock for `actorId` via `open(path, "wx")`
+   * (atomic create-if-absent). Retries with jittered backoff while the lock is
+   * held elsewhere, and steals locks left behind by a crashed process once
+   * they're older than `staleMs`.
+   */
+  async _acquireFileLock(actorId) {
+    const lockPath = `${this._filePath(actorId)}.lock`;
+    const staleMs = 1e4;
+    const timeoutMs = 3e4;
+    const start = Date.now();
+    while (true) {
+      try {
+        const handle = await open(lockPath, "wx");
+        await handle.close();
+        return async () => {
+          await unlink(lockPath).catch(() => {
+          });
+        };
+      } catch (err) {
+        if (err.code !== "EEXIST") {
+          throw storageError(`Failed to acquire lock for actor ${actorId}: ${err.message}`);
+        }
+        try {
+          const st = await stat(lockPath);
+          if (Date.now() - st.mtimeMs > staleMs) {
+            await unlink(lockPath).catch(() => {
+            });
+            continue;
+          }
+        } catch {
+          continue;
+        }
+        if (Date.now() - start > timeoutMs) {
+          throw storageError(`Timed out waiting for disk storage lock: ${lockPath}`);
+        }
+        await new Promise((r) => setTimeout(r, 15 + Math.random() * 35));
+      }
+    }
+  }
   async _listActors() {
     try {
       const entries = await readdir(this.dir);
@@ -1380,7 +1445,7 @@ var MarkdownStorageAdapter = class {
       sourceId: input.sourceId,
       metadata: input.metadata ?? {},
       expiresAt: input.expiresAt,
-      createdAt: now
+      createdAt: input.createdAt ?? now
     };
     const filePath = this._filePath(input.actorId);
     const block = this._formatBlock(memory);
@@ -1457,8 +1522,11 @@ var MarkdownStorageAdapter = class {
       results = results.filter((m) => m.tags?.some((t) => query.tags.includes(t)));
     }
     if (query.query) {
-      const q = query.query.toLowerCase();
-      results = results.filter((m) => m.content.toLowerCase().includes(q));
+      const terms = query.query.toLowerCase().split(/\s+/).filter(Boolean);
+      results = results.filter((m) => {
+        const content = m.content.toLowerCase();
+        return terms.some((t) => content.includes(t));
+      });
     }
     switch (query.strategy) {
       case "recent":
@@ -2009,7 +2077,7 @@ var PostgresStorageAdapter = class {
       sourceId: input.sourceId,
       metadata: input.metadata ?? {},
       expiresAt: input.expiresAt,
-      createdAt: new Date(now)
+      createdAt: input.createdAt ?? new Date(now)
     };
   }
   async storeBatch(inputs) {
@@ -2212,7 +2280,7 @@ var RedisStorageAdapter = class {
       sourceId: input.sourceId,
       metadata: input.metadata ?? {},
       expiresAt: input.expiresAt,
-      createdAt: now,
+      createdAt: input.createdAt ?? now,
       _touchedAt: now.toISOString()
     };
     await this.redis.set(this._memKey(memory.id), JSON.stringify(memory));
@@ -2236,7 +2304,7 @@ var RedisStorageAdapter = class {
         sourceId: input.sourceId,
         metadata: input.metadata ?? {},
         expiresAt: input.expiresAt,
-        createdAt: now,
+        createdAt: input.createdAt ?? now,
         _touchedAt: now.toISOString()
       };
       await this.redis.set(this._memKey(memory.id), JSON.stringify(memory));
@@ -2432,7 +2500,7 @@ var QdrantStorageAdapter = class {
       sourceId: input.sourceId,
       metadata: input.metadata ?? {},
       expiresAt: input.expiresAt,
-      createdAt: now
+      createdAt: input.createdAt ?? now
     };
     const qdrantId = crypto.randomUUID();
     await this.client.upsert(this.collectionName, {
@@ -2464,7 +2532,7 @@ var QdrantStorageAdapter = class {
         sourceId: input.sourceId,
         metadata: input.metadata ?? {},
         expiresAt: input.expiresAt,
-        createdAt: now
+        createdAt: input.createdAt ?? now
       };
       results.push(memory);
       const qid = crypto.randomUUID();
@@ -2642,10 +2710,13 @@ var Neo4jStorageAdapter = class {
       sourceId: input.sourceId ?? null,
       metadata: JSON.stringify(input.metadata ?? {}),
       expiresAt: input.expiresAt?.toISOString() ?? null,
-      createdAt: now,
+      createdAt: input.createdAt?.toISOString() ?? now,
       embedding: input.embedding ?? null
     };
-    const { createdAt: _, ...updateProps } = props;
+    const updateProps = { ...props };
+    if (!input.createdAt) {
+      delete updateProps.createdAt;
+    }
     const session = this.driver.session({ database: this.database });
     try {
       await session.run(
@@ -2667,7 +2738,7 @@ var Neo4jStorageAdapter = class {
       sourceId: input.sourceId,
       metadata: input.metadata ?? {},
       expiresAt: input.expiresAt,
-      createdAt: new Date(now)
+      createdAt: input.createdAt ?? new Date(now)
     };
   }
   async storeBatch(inputs) {
@@ -2904,7 +2975,7 @@ var WeaviateStorageAdapter = class {
       sourceId: input.sourceId,
       metadata: input.metadata ?? {},
       expiresAt: input.expiresAt,
-      createdAt: now
+      createdAt: input.createdAt ?? now
     };
     const wvId = await this.collection().data.insert({
       id: crypto.randomUUID(),
@@ -3137,7 +3208,7 @@ var LanceDBStorageAdapter = class {
       sourceId: input.sourceId,
       metadata: input.metadata ?? {},
       expiresAt: input.expiresAt,
-      createdAt: now
+      createdAt: input.createdAt ?? now
     };
   }
   async storeBatch(inputs) {
@@ -3305,7 +3376,7 @@ var MongoDBStorageAdapter = class {
       sourceId: input.sourceId,
       metadata: input.metadata ?? {},
       expiresAt: input.expiresAt,
-      createdAt: now
+      createdAt: input.createdAt ?? now
     };
     await this.collection.insertOne(this.toDoc(memory));
     return memory;
@@ -3534,7 +3605,7 @@ var SQLiteStorageAdapter = class {
       sourceId: input.sourceId,
       metadata: input.metadata ?? {},
       expiresAt: input.expiresAt,
-      createdAt: new Date(now)
+      createdAt: input.createdAt ?? new Date(now)
     };
   }
   async storeBatch(inputs) {
@@ -3807,11 +3878,12 @@ var OpenAILLMAdapter = class {
           try {
             const parsed = JSON.parse(data);
             const content = parsed.choices?.[0]?.delta?.content ?? "";
-            if (parsed.usage) {
-              promptTokens = parsed.usage.prompt_tokens;
-              completionTokens = parsed.usage.completion_tokens;
+            const usage = parsed.usage;
+            if (usage) {
+              promptTokens = usage.prompt_tokens;
+              completionTokens = usage.completion_tokens;
             }
-            if (content) {
+            if (content || usage) {
               yield {
                 text: content,
                 tokens: { prompt: promptTokens, completion: completionTokens, total: promptTokens + completionTokens }
@@ -3867,7 +3939,15 @@ var AnthropicLLMAdapter = class {
       };
     } catch (err) {
       if (err instanceof MemStackError) throw err;
-      throw new MemStackError("LLM_ERROR", `Anthropic request failed: ${err instanceof Error ? err.message : String(err)}`, {
+      const msg = err instanceof Error ? err.message : String(err);
+      const code = err?.code;
+      const isMissingSdk = msg.includes("@anthropic-ai/sdk") && (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND" || /cannot find (package|module)/i.test(msg) || /failed to (load|resolve)/i.test(msg));
+      if (isMissingSdk) {
+        throw new MemStackError("LLM_ERROR", "Anthropic adapter requires @anthropic-ai/sdk. Install it: npm install @anthropic-ai/sdk", {
+          retryable: false
+        });
+      }
+      throw new MemStackError("LLM_ERROR", `Anthropic request failed: ${msg}`, {
         retryable: true
       });
     }
@@ -4156,7 +4236,7 @@ var GroqLLMAdapter = class {
               promptTokens = usage.prompt_tokens;
               completionTokens = usage.completion_tokens;
             }
-            if (content) {
+            if (content || usage) {
               yield {
                 text: content,
                 tokens: { prompt: promptTokens, completion: completionTokens, total: promptTokens + completionTokens }