@agent-diaries/core 0.1.4 → 1.0.0

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 }) 
 });
 ```
 

package/dist/adapters/mongo.d.ts

@@ -1,14 +1,16 @@
 import { StorageAdapter } from '../storage';
 import { Collection } from 'mongodb';
+interface MongoStorageOptions {
+    collection: Collection;
+}
 export declare class MongoStorage<T> implements StorageAdapter<T> {
     private collection;
-    private initialized;
-    constructor(config: {
-        collection: Collection;
-    });
+    private static indexedCollections;
+    constructor(options: MongoStorageOptions);
     private ensureIndex;
     private hashString;
     get(key: string): Promise<T | null>;
     set(key: string, data: T): Promise<void>;
     withLock<R>(key: string, fn: () => Promise<R>): Promise<R>;
 }
+export {};

package/dist/adapters/mongo.js

@@ -7,20 +7,21 @@ exports.MongoStorage = void 0;
 const crypto_1 = __importDefault(require("crypto"));
 class MongoStorage {
     collection;
-    initialized = false;
-    constructor(config) {
-        this.collection = config.collection;
+    static indexedCollections = new Set();
+    constructor(options) {
+        this.collection = options.collection;
     }
     async ensureIndex() {
-        if (this.initialized)
+        const ns = this.collection.namespace;
+        if (MongoStorage.indexedCollections.has(ns))
             return;
         try {
-            await this.collection.createIndex({ lockedAt: 1 }, { expireAfterSeconds: 30, partialFilterExpression: { lockedAt: { $exists: true } } });
+            await this.collection.createIndex({ lockedAt: 1 }, { expireAfterSeconds: 10, partialFilterExpression: { lockedAt: { $exists: true } } });
         }
         catch (e) {
             console.warn('[MongoStorage] Failed to create TTL index:', e);
         }
-        this.initialized = true;
+        MongoStorage.indexedCollections.add(ns);
     }
     hashString(str) {
         return crypto_1.default.createHash('sha256').update(str).digest('hex');
@@ -57,8 +58,9 @@ class MongoStorage {
             const jitter = Math.random() * 50;
             await new Promise(resolve => setTimeout(resolve, backoff + jitter));
             attempt++;
-            if (attempt > 60)
+            if (attempt > 150) {
                 throw new Error(`[MongoStorage] Lock timeout on key: ${key}`);
+            }
         }
         try {
             return await fn();

package/dist/diary.js

@@ -107,13 +107,8 @@ class AgentDiary {
                 await this.storage.set(`diary_${this.agentId}`, state);
             }
             else {
-                // If not claimed first, we insert it
-                const record = { title, signature, result, timestamp: Date.now() };
-                state.history = [record, ...state.history].slice(0, this.maxHistory);
-                state.seenSignatures = state.history.map(r => r.signature);
-                state.runCount += 1;
-                state.lastRun = Date.now();
-                await this.storage.set(`diary_${this.agentId}`, state);
+                // If not claimed first, we throw a loud error
+                throw new Error(`[AgentDiary] Task "${title}" was not claimed. Call claimTask() before writeTaskResult().`);
             }
         });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-diaries/core",
-  "version": "0.1.4",
+  "version": "1.0.0",
   "description": "The lightweight, framework-agnostic memory layer for edge AI agents.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",