@agent-diaries/core 0.1.3 → 0.1.41

package/README.md

@@ -69,6 +69,35 @@ async function runAgent() {
 
 runAgent();
 ```
+### Forcefully Re-running a Task (The Engineering Trick)
+
+If you want an agent to strictly avoid duplicate work, use `await diary.claimTask(task)`. It will automatically return `false` if it was done.
+
+But if an agent wants to explicitly overwrite or re-do a task because the user demanded it, you skip `claimTask()` entirely and just write the final result using `await diary.writeTaskResult(task, newResult)`. This seamlessly replaces the old memory with the new one.
+
+```text
+🤖 Agent Alice: Claiming and performing 'Generate Monthly Report'...
+   -> Task done! Saving result.
+--------------------------------------------------
+🤖 Agent Bob: Checking if 'Generate Monthly Report' is done...
+   -> 🛑 Found in Diary! Previous result: "Report for May: $12,000 Revenue."
+   -> 💬 Informs User: "This report was already generated. Do you want me to re-run it with the latest data?"
+   -> 👤 User responds: YES
+   -> Agent Bob forcefully re-running the task... 
+```
+
+```typescript
+// 1. Check if it's already done (for logging/informing user)
+if (await diary.hasProcessedTask(currentTask)) {
+  console.log("Task is already done. Forcefully re-running per user request...");
+}
+
+// 2. Perform the work again
+const updatedResult = "Found 0 warnings, ALL critical errors resolved.";
+
+// 3. Skip claimTask() and directly overwrite the old memory
+await diary.writeTaskResult(currentTask, updatedResult);
+```
 
 ## ☁️ Cloud Storage Adapters (Production)
 
@@ -88,20 +117,21 @@ const diary = new AgentDiary({
 });
 ```
 
-### PostgreSQL (Best for Stateful Architectures)
-The `PostgresStorage` adapter natively uses `pg_advisory_lock` to ensure absolute row-level safety during concurrent task evaluation.
+### MongoDB (Best for Document Scaling)
+The `MongoStorage` adapter natively uses atomic `_id` unique insertion constraints to guarantee row-level safety during concurrent task evaluation, with built-in TTL lock expiration.
 
 ```typescript
 import { AgentDiary } from '@agent-diaries/core';
-import { PostgresStorage } from '@agent-diaries/core/dist/adapters/postgres';
-import { Pool } from 'pg';
+import { MongoStorage } from '@agent-diaries/core/dist/adapters/mongo';
+import { MongoClient } from 'mongodb';
 
-const pgStorage = new PostgresStorage({ pool: new Pool({ connectionString: process.env.DATABASE_URL }) });
-await pgStorage.initialize(); // Creates the state table
+const client = new MongoClient(process.env.MONGO_URI);
+await client.connect();
+const collection = client.db('agent_diaries').collection('tasks');
 
 const diary = new AgentDiary({ 
   agentId: 'db-bot',
-  storage: pgStorage 
+  storage: new MongoStorage({ collection }) 
 });
 ```
 
@@ -183,6 +213,7 @@ console.log(`   Actual Locks: ${successful}`); // Always exactly 1.
   Retrieves the exact string output/result from a previously completed task so your agent can instantly reuse it.
 - **`diary.filterNewTasks(tasks: T[]): Promise<T[]>`**
   Pass in an array of task objects. Returns only the tasks that the agent has *not* seen yet.
+  *⚠️ WARNING: This method returns a non-atomic snapshot. Always follow up with `claimTask()` on individual items before acting on them in a high-concurrency environment.*
 - **`diary.writeTaskResult(title: string, result: string): Promise<void>`**
   Saves the final result into the agent's memory bank after the agent finishes its work.
 

package/dist/adapters/mongo.d.ts

@@ -2,9 +2,11 @@ import { StorageAdapter } from '../storage';
 import { Collection } from 'mongodb';
 export declare class MongoStorage<T> implements StorageAdapter<T> {
     private collection;
+    private initialized;
     constructor(config: {
         collection: Collection;
     });
+    private ensureIndex;
     private hashString;
     get(key: string): Promise<T | null>;
     set(key: string, data: T): Promise<void>;

package/dist/adapters/mongo.js

@@ -7,9 +7,21 @@ exports.MongoStorage = void 0;
 const crypto_1 = __importDefault(require("crypto"));
 class MongoStorage {
     collection;
+    initialized = false;
     constructor(config) {
         this.collection = config.collection;
     }
+    async ensureIndex() {
+        if (this.initialized)
+            return;
+        try {
+            await this.collection.createIndex({ lockedAt: 1 }, { expireAfterSeconds: 30, partialFilterExpression: { lockedAt: { $exists: true } } });
+        }
+        catch (e) {
+            console.warn('[MongoStorage] Failed to create TTL index:', e);
+        }
+        this.initialized = true;
+    }
     hashString(str) {
         return crypto_1.default.createHash('sha256').update(str).digest('hex');
     }
@@ -25,6 +37,7 @@ class MongoStorage {
         await this.collection.updateOne({ _id: hash }, { $set: { data: JSON.stringify(data) } }, { upsert: true });
     }
     async withLock(key, fn) {
+        await this.ensureIndex();
         const hash = this.hashString(key);
         const lockId = `lock:${hash}`;
         const acquireLock = async () => {
@@ -38,8 +51,14 @@ class MongoStorage {
                 throw error;
             }
         };
+        let attempt = 0;
         while (!(await acquireLock())) {
-            await new Promise(resolve => setTimeout(resolve, 50));
+            const backoff = Math.min(10 * Math.pow(2, attempt), 500);
+            const jitter = Math.random() * 50;
+            await new Promise(resolve => setTimeout(resolve, backoff + jitter));
+            attempt++;
+            if (attempt > 60)
+                throw new Error(`[MongoStorage] Lock timeout on key: ${key}`);
         }
         try {
             return await fn();

package/dist/adapters/redis.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RedisStorage = void 0;
+const crypto_1 = require("crypto");
 class RedisStorage {
     redis;
     prefix;
@@ -29,15 +30,20 @@ class RedisStorage {
     }
     async withLock(key, fn) {
         const lockKey = `${this.getKey(key)}:lock`;
-        const lockValue = Date.now().toString() + Math.random().toString();
+        const lockValue = (0, crypto_1.randomUUID)();
         const lockTtlMs = 10000; // 10 seconds max lock
         const acquireLock = async () => {
             const result = await this.redis.set(lockKey, lockValue, 'PX', lockTtlMs, 'NX');
             return result === 'OK';
         };
-        // Spin-lock until we acquire it
+        let attempt = 0;
         while (!(await acquireLock())) {
-            await new Promise((resolve) => setTimeout(resolve, 50));
+            const backoff = Math.min(10 * Math.pow(2, attempt), 500);
+            const jitter = Math.random() * 50;
+            await new Promise(resolve => setTimeout(resolve, backoff + jitter));
+            attempt++;
+            if (attempt > 60)
+                throw new Error(`[RedisStorage] Lock timeout on key: ${key}`);
         }
         try {
             return await fn();

package/dist/diary.d.ts

@@ -45,6 +45,9 @@ export declare class AgentDiary {
     getTaskResult(title: string): Promise<string | undefined>;
     /**
      * Filters out items that the agent has already processed.
+     *
+     * ⚠️ WARNING: filterNewTasks() is a non-atomic snapshot. Always follow it with claimTask()
+     * to atomically claim ownership. Never act on filterNewTasks() results directly without claiming them first.
      */
     filterNewTasks<T extends {
         title: string;

package/dist/diary.js

@@ -41,7 +41,8 @@ class AgentDiary {
         const signature = AgentDiary.normalizeSignature(title);
         return await this.storage.withLock(`diary_${this.agentId}`, async () => {
             const state = await this.readDiary();
-            if (state.seenSignatures.includes(signature)) {
+            const seenSet = new Set(state.seenSignatures);
+            if (seenSet.has(signature)) {
                 return false; // Task already exists
             }
             // Claim it immediately to prevent race conditions
@@ -65,7 +66,8 @@ class AgentDiary {
     async hasProcessedTask(title) {
         const signature = AgentDiary.normalizeSignature(title);
         const state = await this.readDiary();
-        return state.seenSignatures.includes(signature);
+        const seenSet = new Set(state.seenSignatures);
+        return seenSet.has(signature);
     }
     /**
      * Retrieves the stored result of a previously processed task, if available.
@@ -78,12 +80,16 @@ class AgentDiary {
     }
     /**
      * Filters out items that the agent has already processed.
+     *
+     * ⚠️ WARNING: filterNewTasks() is a non-atomic snapshot. Always follow it with claimTask()
+     * to atomically claim ownership. Never act on filterNewTasks() results directly without claiming them first.
      */
     async filterNewTasks(tasks) {
         const state = await this.readDiary();
+        const seenSet = new Set(state.seenSignatures);
         return tasks.filter(task => {
             const signature = AgentDiary.normalizeSignature(task.title);
-            return !state.seenSignatures.includes(signature);
+            return !seenSet.has(signature);
         });
     }
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-diaries/core",
-  "version": "0.1.3",
+  "version": "0.1.41",
   "description": "The lightweight, framework-agnostic memory layer for edge AI agents.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -14,11 +14,15 @@
     "prepublishOnly": "npm run build"
   },
   "keywords": [
-    "ai",
-    "agent",
-    "memory",
-    "diary",
-    "local"
+    "ai-agent",
+    "agent-memory",
+    "deduplication",
+    "distributed-lock",
+    "redis",
+    "mongodb",
+    "serverless",
+    "idempotency",
+    "task-queue"
   ],
   "author": "swapwarick_n",
   "repository": {
@@ -31,6 +35,7 @@
   "homepage": "https://github.com/swapwarick/agent-diaries-core#readme",
   "license": "MIT",
   "devDependencies": {
+    "dotenv": "^17.4.2",
     "@types/dotenv": "^6.1.1",
     "@types/node": "^20.0.0",
     "@types/proper-lockfile": "^4.1.4",
@@ -40,9 +45,18 @@
     "vitest": "^4.1.5"
   },
   "dependencies": {
-    "dotenv": "^17.4.2",
-    "ioredis": "^5.10.1",
-    "mongodb": "^7.2.0",
     "proper-lockfile": "^4.1.2"
+  },
+  "peerDependencies": {
+    "ioredis": ">=5",
+    "mongodb": ">=6"
+  },
+  "peerDependenciesMeta": {
+    "ioredis": {
+      "optional": true
+    },
+    "mongodb": {
+      "optional": true
+    }
   }
 }