@kuralle-agents/postgres-store 0.5.0 → 0.6.1

package/README.md

@@ -18,6 +18,7 @@ Three backend implementations — sessions, long-term memory, and pgvector simil
 
 - **`PostgresSessionStore`** — `SessionStore` implementation for durable session persistence.
 - **`PostgresMemoryService`** — `MemoryService` implementation for cross-session long-term memory.
+- **`PostgresPersistentMemoryStore`** — `PersistentMemoryStore` for durable USER/MEMORY markdown blocks.
 - **`PgVectorStore`** — `VectorStoreCore` implementation using pgvector for similarity search.
 
 ## Session store
@@ -58,6 +59,22 @@ const runtime = createRuntime({
 });
 ```
 
+## Working memory blocks
+
+```ts
+import { PostgresPersistentMemoryStore } from '@kuralle-agents/postgres-store';
+
+const workingMemoryStore = new PostgresPersistentMemoryStore({ client: pool });
+
+const runtime = createRuntime({
+  agents: [agent],
+  defaultAgentId: 'support',
+  defaultWorkingMemoryStore: workingMemoryStore,
+});
+```
+
+On Cloudflare Workers, connect the pool through [Hyperdrive](https://developers.cloudflare.com/hyperdrive/) rather than a direct TCP connection.
+
 ## Vector store (pgvector)
 
 Requires the `pgvector` extension in your Postgres instance.

package/dist/PostgresPersistentMemoryStore.d.ts

@@ -0,0 +1,22 @@
+import type { MemoryBlockScope, PersistentMemoryBlock, PersistentMemoryStore } from '@kuralle-agents/core';
+import type { QueryResult } from 'pg';
+type PostgresClient = {
+    query: (text: string, params?: unknown[]) => Promise<QueryResult>;
+};
+export type PostgresPersistentMemoryStoreOptions = {
+    client: PostgresClient;
+    tableName?: string;
+    autoMigrate?: boolean;
+};
+export declare class PostgresPersistentMemoryStore implements PersistentMemoryStore {
+    private client;
+    private table;
+    private ready;
+    constructor(options: PostgresPersistentMemoryStoreOptions);
+    private init;
+    loadBlock(scope: MemoryBlockScope, owner: string, key: string): Promise<PersistentMemoryBlock | null>;
+    saveBlock(block: PersistentMemoryBlock, owner: string): Promise<void>;
+    deleteBlock(scope: MemoryBlockScope, owner: string, key: string): Promise<void>;
+    listBlocks(scope: MemoryBlockScope, owner: string): Promise<string[]>;
+}
+export {};

package/dist/PostgresPersistentMemoryStore.js

@@ -0,0 +1,70 @@
+const defaultTable = 'working_memory_blocks';
+const normalizeTableName = (tableName) => {
+    const table = tableName ?? defaultTable;
+    if (!/^[a-zA-Z0-9_.]+$/.test(table)) {
+        throw new Error(`Invalid table name: ${table}`);
+    }
+    return table;
+};
+export class PostgresPersistentMemoryStore {
+    client;
+    table;
+    ready;
+    constructor(options) {
+        this.client = options.client;
+        this.table = normalizeTableName(options.tableName);
+        const autoMigrate = options.autoMigrate ?? true;
+        this.ready = autoMigrate ? this.init() : Promise.resolve();
+    }
+    async init() {
+        await this.client.query(`CREATE TABLE IF NOT EXISTS ${this.table} (
+        scope TEXT NOT NULL,
+        owner TEXT NOT NULL,
+        key TEXT NOT NULL,
+        content TEXT NOT NULL,
+        char_limit INTEGER NOT NULL,
+        updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+        PRIMARY KEY (scope, owner, key)
+      )`);
+        await this.client.query(`CREATE INDEX IF NOT EXISTS idx_${this.table}_scope_owner
+       ON ${this.table} (scope, owner)`);
+    }
+    async loadBlock(scope, owner, key) {
+        await this.ready;
+        const result = await this.client.query(`SELECT content, char_limit, updated_at
+       FROM ${this.table}
+       WHERE scope = $1 AND owner = $2 AND key = $3`, [scope, owner, key]);
+        if (result.rows.length === 0) {
+            return null;
+        }
+        const row = result.rows[0];
+        return {
+            key,
+            scope,
+            content: row.content,
+            charLimit: row.char_limit,
+            updatedAt: new Date(row.updated_at).toISOString(),
+        };
+    }
+    async saveBlock(block, owner) {
+        await this.ready;
+        const updatedAt = block.updatedAt ?? new Date().toISOString();
+        await this.client.query(`INSERT INTO ${this.table} (scope, owner, key, content, char_limit, updated_at)
+       VALUES ($1, $2, $3, $4, $5, $6)
+       ON CONFLICT (scope, owner, key) DO UPDATE SET
+         content = EXCLUDED.content,
+         char_limit = EXCLUDED.char_limit,
+         updated_at = EXCLUDED.updated_at`, [block.scope, owner, block.key, block.content, block.charLimit, updatedAt]);
+    }
+    async deleteBlock(scope, owner, key) {
+        await this.ready;
+        await this.client.query(`DELETE FROM ${this.table} WHERE scope = $1 AND owner = $2 AND key = $3`, [scope, owner, key]);
+    }
+    async listBlocks(scope, owner) {
+        await this.ready;
+        const result = await this.client.query(`SELECT key FROM ${this.table}
+       WHERE scope = $1 AND owner = $2
+       ORDER BY key`, [scope, owner]);
+        return result.rows.map((row) => row.key);
+    }
+}

package/dist/index.d.ts

@@ -2,5 +2,7 @@ export { PostgresSessionStore } from './PostgresSessionStore.js';
 export type { PostgresStoreOptions } from './PostgresSessionStore.js';
 export { PostgresMemoryService } from './PostgresMemoryService.js';
 export type { PostgresMemoryStoreOptions } from './PostgresMemoryService.js';
+export { PostgresPersistentMemoryStore } from './PostgresPersistentMemoryStore.js';
+export type { PostgresPersistentMemoryStoreOptions } from './PostgresPersistentMemoryStore.js';
 export { PgVectorStore } from './PgVectorStore.js';
 export type { PgVectorStoreOptions } from './PgVectorStore.js';

package/dist/index.js

@@ -1,3 +1,4 @@
 export { PostgresSessionStore } from './PostgresSessionStore.js';
 export { PostgresMemoryService } from './PostgresMemoryService.js';
+export { PostgresPersistentMemoryStore } from './PostgresPersistentMemoryStore.js';
 export { PgVectorStore } from './PgVectorStore.js';

package/package.json

@@ -6,7 +6,7 @@
     "url": "git+https://github.com/kuralle/kuralle-agents.git",
     "directory": "packages/kuralle-postgres-store"
   },
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "PostgreSQL-backed SessionStore for Kuralle",
   "type": "module",
   "main": "dist/index.js",
@@ -18,19 +18,19 @@
     }
   },
   "dependencies": {
-    "@kuralle-agents/core": "0.5.0"
+    "@kuralle-agents/core": "0.6.1"
   },
   "peerDependencies": {
     "pg": "^8.0.0",
-    "@kuralle-agents/core": "0.5.0",
-    "@kuralle-agents/rag": "0.5.0"
+    "@kuralle-agents/core": "0.6.1",
+    "@kuralle-agents/rag": "0.6.1"
   },
   "devDependencies": {
     "@types/node": "^20.11.0",
     "@types/pg": "^8.11.0",
     "pg": "^8.11.0",
     "typescript": "^5.3.0",
-    "@kuralle-agents/rag": "0.5.0"
+    "@kuralle-agents/rag": "0.6.1"
   },
   "publishConfig": {
     "access": "public"