@agent-diaries/core 1.0.0 → 1.1.0

package/README.md

@@ -29,11 +29,12 @@ Install the core package:
 npm install @agent-diaries/core
 ```
 
-If you plan to use a specific cloud adapter, install its peer dependency:
+If you plan to use a specific storage adapter, install its peer dependency:
 
 ```bash
-npm install ioredis    # For Redis Storage
-npm install mongodb    # For MongoDB Storage
+npm install better-sqlite3 # For SQLite Storage
+npm install ioredis        # For Redis Storage
+npm install mongodb        # For MongoDB Storage
 ```
 
 ## 🚀 Quick Start
@@ -99,11 +100,26 @@ const updatedResult = "Found 0 warnings, ALL critical errors resolved.";
 await diary.writeTaskResult(currentTask, updatedResult);
 ```
 
-## ☁️ Cloud Storage Adapters (Production)
+## 🗄️ Storage Adapters (Cloud & Local Databases)
 
-Local file storage is great for local development, but serverless environments (Vercel, AWS Lambda) have ephemeral filesystems. For production, you **must** use one of our lock-safe cloud adapters.
+Local file storage is great for local development, but serverless environments (Vercel, AWS Lambda) have ephemeral filesystems and require lock-safe cloud adapters, while local tools and desktops benefit from relational SQLite coordination.
 
-### Redis (Best for Serverless)
+### SQLite (Best for Desktop / Local Apps)
+The `SqliteStorage` adapter uses a local SQLite database (`better-sqlite3`) with atomic UNIQUE constraint insertions and transactional TTL locks for highly reliable multi-process coordination.
+
+```typescript
+import { AgentDiary } from '@agent-diaries/core';
+import { SqliteStorage } from '@agent-diaries/core/dist/adapters/sqlite';
+import Database from 'better-sqlite3';
+
+const db = new Database('diary.db');
+const diary = new AgentDiary({ 
+  agentId: 'sqlite-bot',
+  storage: new SqliteStorage({ db }) 
+});
+```
+
+### Redis (Best for Serverless / Swarms)
 The `RedisStorage` adapter uses atomic `SETNX` distributed spin-locks to guarantee race-condition safety across thousands of concurrent Vercel Edge functions.
 
 ```typescript
@@ -135,13 +151,32 @@ const diary = new AgentDiary({
 });
 ```
 
-## 📊 200-Agent Real-World Cloud Benchmarks
+## 📊 Enterprise Concurrency Benchmarks
 
 Agent Diaries Core is mathematically proven to handle massive concurrent agent swarms without race conditions or database corruption. 
 
-To prove its viability for enterprise serverless deployments, we rigorously stress-tested the library against a **Live Cloud Upstash Redis Database**, blasting it with **200 serverless agents** executing distributed lock requests across the internet at the exact same millisecond.
+### 1. Multi-Process OS-Level Concurrency (Worker Threads)
+To verify true operating-system level process isolation, we spawned 50 independent Node.js `worker_threads` to aggressively hit the cloud databases at the exact same millisecond.
+
+```text
+🌪️ Spawning 50 Multi-Process Workers for REDIS...
+   Expected Locks: 1
+   Actual Locks:   1
+   Resolution Time: ~4300ms
+   🟢 PASSED (49 race conditions prevented across OS processes)
+
+🌪️ Spawning 50 Multi-Process Workers for MONGO...
+   Expected Locks: 1
+   Actual Locks:   1
+   Resolution Time: 8192ms
+   🟢 PASSED (49 race conditions prevented across OS processes)
+```
+
+### 2. 200-Agent Real-World Cloud Scale
+
+To prove its viability for global serverless deployments, we rigorously stress-tested the library against live instances, blasting them with **200 serverless agents** executing distributed lock requests across the internet simultaneously.
 
-### The Real-Life Architecture
+#### The Real-Life Architecture
 ```typescript
 const NUM_AGENTS = 200;
 let agents = Array.from({ length: NUM_AGENTS }, () => getDiary());

package/dist/adapters/sqlite.d.ts

@@ -0,0 +1,16 @@
+import { StorageAdapter } from '../storage';
+import type { Database } from 'better-sqlite3';
+export interface SqliteStorageOptions {
+    db: Database;
+    tableName?: string;
+    locksTableName?: string;
+}
+export declare class SqliteStorage<T> implements StorageAdapter<T> {
+    private db;
+    private tableName;
+    private locksTableName;
+    constructor(options: SqliteStorageOptions);
+    get(key: string): Promise<T | null>;
+    set(key: string, value: T): Promise<void>;
+    withLock<R>(key: string, fn: () => Promise<R>): Promise<R>;
+}

package/dist/adapters/sqlite.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SqliteStorage = void 0;
+class SqliteStorage {
+    db;
+    tableName;
+    locksTableName;
+    constructor(options) {
+        if (!options.db) {
+            throw new Error('[SqliteStorage] database instance (db) is required.');
+        }
+        this.db = options.db;
+        this.tableName = options.tableName || 'agent_diaries_storage';
+        this.locksTableName = options.locksTableName || 'agent_diaries_locks';
+        // Initialize tables synchronously as better-sqlite3 is fully synchronous
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS ${this.tableName} (
+        key TEXT PRIMARY KEY,
+        value TEXT
+      );
+      CREATE TABLE IF NOT EXISTS ${this.locksTableName} (
+        key TEXT PRIMARY KEY,
+        locked_at INTEGER
+      );
+    `);
+    }
+    async get(key) {
+        try {
+            const row = this.db
+                .prepare(`SELECT value FROM ${this.tableName} WHERE key = ?`)
+                .get(key);
+            if (!row)
+                return null;
+            return JSON.parse(row.value);
+        }
+        catch (e) {
+            console.error(`[SqliteStorage] Failed to get key ${key}:`, e);
+            return null;
+        }
+    }
+    async set(key, value) {
+        try {
+            const serialized = JSON.stringify(value);
+            this.db
+                .prepare(`
+          INSERT INTO ${this.tableName} (key, value)
+          VALUES (?, ?)
+          ON CONFLICT(key) DO UPDATE SET value = excluded.value
+        `)
+                .run(key, serialized);
+        }
+        catch (e) {
+            console.error(`[SqliteStorage] Failed to set key ${key}:`, e);
+            throw e;
+        }
+    }
+    async withLock(key, fn) {
+        const lockKey = `lock:${key}`;
+        const lockTtlMs = 10000; // 10 seconds max lock
+        const acquireLock = () => {
+            const now = Date.now();
+            try {
+                this.db
+                    .prepare(`INSERT INTO ${this.locksTableName} (key, locked_at) VALUES (?, ?)`)
+                    .run(lockKey, now);
+                return true;
+            }
+            catch (error) {
+                if (error.code === 'SQLITE_CONSTRAINT_PRIMARYKEY' ||
+                    error.code === 'SQLITE_CONSTRAINT' ||
+                    (error.message && error.message.includes('UNIQUE constraint failed'))) {
+                    // Check if the lock has expired
+                    const existing = this.db
+                        .prepare(`SELECT locked_at FROM ${this.locksTableName} WHERE key = ?`)
+                        .get(lockKey);
+                    if (existing && now - existing.locked_at > lockTtlMs) {
+                        // Attempt to clear the expired lock and acquire it
+                        try {
+                            // Wrap cleanup and acquire in a transaction for atomicity
+                            const runCleanupAndAcquire = this.db.transaction(() => {
+                                this.db
+                                    .prepare(`DELETE FROM ${this.locksTableName} WHERE key = ? AND locked_at = ?`)
+                                    .run(lockKey, existing.locked_at);
+                                this.db
+                                    .prepare(`INSERT INTO ${this.locksTableName} (key, locked_at) VALUES (?, ?)`)
+                                    .run(lockKey, now);
+                            });
+                            runCleanupAndAcquire();
+                            return true;
+                        }
+                        catch (retryError) {
+                            // Conflict during retry, lock is still held or acquired by another concurrent process
+                            return false;
+                        }
+                    }
+                    return false;
+                }
+                throw error;
+            }
+        };
+        let attempt = 0;
+        while (!acquireLock()) {
+            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(`[SqliteStorage] Lock timeout on key: ${key}`);
+            }
+        }
+        try {
+            return await fn();
+        }
+        finally {
+            try {
+                this.db
+                    .prepare(`DELETE FROM ${this.locksTableName} WHERE key = ?`)
+                    .run(lockKey);
+            }
+            catch (e) {
+                console.error(`[SqliteStorage] Failed to release lock on key ${key}:`, e);
+            }
+        }
+    }
+}
+exports.SqliteStorage = SqliteStorage;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-diaries/core",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "The lightweight, framework-agnostic memory layer for edge AI agents.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,7 +9,7 @@
   ],
   "scripts": {
     "test": "vitest run",
-    "test:coverage": "vitest run --coverage",
+    "test:coverage": "vitest run --coverage.reporter=lcov --coverage.reporter=text",
     "build": "tsc",
     "prepublishOnly": "npm run build"
   },
@@ -35,23 +35,31 @@
   "homepage": "https://github.com/swapwarick/agent-diaries-core#readme",
   "license": "MIT",
   "devDependencies": {
-    "dotenv": "^17.4.2",
+    "@types/better-sqlite3": "^7.6.11",
     "@types/dotenv": "^6.1.1",
     "@types/node": "^20.0.0",
     "@types/proper-lockfile": "^4.1.4",
     "@vitest/coverage-v8": "^4.1.5",
+    "dotenv": "^17.4.2",
+    "ioredis": "^5.5.0",
+    "mongodb": "^6.13.0",
     "ts-node": "^10.9.2",
     "typescript": "^5.0.0",
     "vitest": "^4.1.5"
   },
   "dependencies": {
+    "mempalace-agent": "^1.0.0",
     "proper-lockfile": "^4.1.2"
   },
   "peerDependencies": {
+    "better-sqlite3": ">=9 || >=10 || >=11",
     "ioredis": ">=5",
     "mongodb": ">=6"
   },
   "peerDependenciesMeta": {
+    "better-sqlite3": {
+      "optional": true
+    },
     "ioredis": {
       "optional": true
     },
@@ -59,4 +67,4 @@
       "optional": true
     }
   }
-}
+}