@anvia/memory-postgres 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Indra Zulfi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,15 @@
+# @anvia/memory-postgres
+
+Postgres-backed durable session memory store for Anvia.
+
+```ts
+import { createPostgresMemoryStore } from "@anvia/memory-postgres";
+
+const memory = await createPostgresMemoryStore({
+  connectionString: process.env.DATABASE_URL,
+});
+```
+
+The package creates the Anvia memory tables by default and writes ordered
+messages transactionally. Pass `createIfMissing: false` when your own migrations
+create the schema.

package/dist/index.d.ts

@@ -0,0 +1,65 @@
+import { MemoryStore, Message } from '@anvia/core';
+import { MemoryAppendInput, MemoryContext, MemoryErrorInput } from '@anvia/core/memory';
+
+type PostgresMemoryErrorMode = "store" | "ignore";
+type PostgresMemoryLockMode = "advisory" | "none";
+type PostgresMemoryQueryResult = {
+    rows: Record<string, unknown>[];
+};
+type PostgresMemoryClientLike = {
+    query(text: string, values?: readonly unknown[]): Promise<PostgresMemoryQueryResult>;
+};
+type PostgresMemoryTransactionClientLike = PostgresMemoryClientLike & {
+    release(): void;
+};
+type PostgresMemoryPoolLike = PostgresMemoryClientLike & {
+    connect(): Promise<PostgresMemoryTransactionClientLike>;
+};
+type PostgresMemoryScopeOptions = {
+    includeUserId?: boolean | undefined;
+    metadataKeys?: string[] | undefined;
+};
+type PostgresMemoryTableNames = {
+    sessions?: string | undefined;
+    messages?: string | undefined;
+    errors?: string | undefined;
+};
+type PostgresMemorySchemaOptions = {
+    tablePrefix?: string | undefined;
+    tableNames?: PostgresMemoryTableNames | undefined;
+};
+type PostgresMemoryStoreOptions = PostgresMemorySchemaOptions & {
+    client?: PostgresMemoryClientLike | undefined;
+    connectionString?: string | undefined;
+    createIfMissing?: boolean | undefined;
+    scope?: PostgresMemoryScopeOptions | ((context: MemoryContext) => string) | undefined;
+    errors?: PostgresMemoryErrorMode | undefined;
+    validateMessages?: boolean | undefined;
+    lock?: PostgresMemoryLockMode | undefined;
+};
+type PostgresMemoryAppendInput = MemoryAppendInput;
+type PostgresMemoryContext = MemoryContext;
+type PostgresMemoryErrorInput = MemoryErrorInput;
+
+declare function createPostgresMemoryStore(options?: PostgresMemoryStoreOptions): Promise<PostgresMemoryStore>;
+declare function createPostgresMemoryScopeKey(context: MemoryContext, options?: PostgresMemoryScopeOptions): string;
+declare function createPostgresMemorySchemaSql(options?: PostgresMemorySchemaOptions): string;
+declare class PostgresMemoryStore implements MemoryStore {
+    private readonly client;
+    private readonly tables;
+    private readonly options;
+    readonly kind = "postgres";
+    private constructor();
+    static connect(options?: PostgresMemoryStoreOptions): Promise<PostgresMemoryStore>;
+    load(context: MemoryContext): Promise<Message[]>;
+    append(input: MemoryAppendInput): Promise<void>;
+    clear(context: MemoryContext): Promise<void>;
+    recordError(input: MemoryErrorInput): Promise<void>;
+    private transaction;
+    private upsertSession;
+    private insertMessages;
+    private messageFromValue;
+    private scopeKey;
+}
+
+export { type PostgresMemoryAppendInput, type PostgresMemoryClientLike, type PostgresMemoryContext, type PostgresMemoryErrorInput, type PostgresMemoryErrorMode, type PostgresMemoryLockMode, type PostgresMemoryPoolLike, type PostgresMemoryQueryResult, type PostgresMemorySchemaOptions, type PostgresMemoryScopeOptions, PostgresMemoryStore, type PostgresMemoryStoreOptions, type PostgresMemoryTableNames, type PostgresMemoryTransactionClientLike, createPostgresMemorySchemaSql, createPostgresMemoryScopeKey, createPostgresMemoryStore };

package/dist/index.js

@@ -0,0 +1,331 @@
+// src/message.ts
+function parseMemoryMessage(value) {
+  if (!isMemoryMessage(value)) {
+    throw new TypeError("Stored Postgres memory row does not contain a valid Anvia Message.");
+  }
+  return value;
+}
+function isMemoryMessage(value) {
+  if (!isRecord(value) || typeof value.role !== "string") {
+    return false;
+  }
+  if (value.role === "system") {
+    return typeof value.content === "string";
+  }
+  if (value.role === "user" || value.role === "assistant" || value.role === "tool") {
+    return Array.isArray(value.content);
+  }
+  return false;
+}
+function serializeUnknownError(error) {
+  if (error instanceof Error) {
+    return {
+      name: error.name,
+      message: error.message,
+      ...error.stack === void 0 ? {} : { stack: error.stack }
+    };
+  }
+  if (isJsonValue(error)) {
+    return error;
+  }
+  return {
+    message: String(error)
+  };
+}
+function isJsonValue(value) {
+  if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return Number.isFinite(value) || typeof value !== "number";
+  }
+  if (Array.isArray(value)) {
+    return value.every(isJsonValue);
+  }
+  return isRecord(value) && Object.values(value).every((item) => item === void 0 || isJsonValue(item));
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/store.ts
+var defaultScopeOptions = {
+  includeUserId: true,
+  metadataKeys: []
+};
+async function createPostgresMemoryStore(options = {}) {
+  return PostgresMemoryStore.connect(options);
+}
+function createPostgresMemoryScopeKey(context, options = {}) {
+  const includeUserId = options.includeUserId ?? defaultScopeOptions.includeUserId;
+  const metadataKeys = options.metadataKeys ?? defaultScopeOptions.metadataKeys;
+  const values = [context.sessionId];
+  if (includeUserId) {
+    values.push(context.userId ?? null);
+  }
+  for (const key of metadataKeys) {
+    values.push(metadataValue(context.metadata, key) ?? null);
+  }
+  return JSON.stringify(values);
+}
+function createPostgresMemorySchemaSql(options = {}) {
+  const tables = resolveTables(options);
+  return `CREATE EXTENSION IF NOT EXISTS pgcrypto;
+
+CREATE TABLE IF NOT EXISTS ${tables.sessions} (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  scope_key text NOT NULL UNIQUE,
+  session_id text NOT NULL,
+  user_id text,
+  metadata jsonb NOT NULL DEFAULT '{}'::jsonb,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS ${tables.messages} (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  memory_session_id uuid NOT NULL REFERENCES ${tables.sessions}(id) ON DELETE CASCADE,
+  run_id text NOT NULL,
+  turn integer NOT NULL,
+  position integer NOT NULL,
+  role text NOT NULL,
+  message jsonb NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS ${tables.messagesPositionIndex}
+  ON ${tables.messages}(memory_session_id, position);
+
+CREATE TABLE IF NOT EXISTS ${tables.errors} (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  memory_session_id uuid NOT NULL REFERENCES ${tables.sessions}(id) ON DELETE CASCADE,
+  run_id text NOT NULL,
+  error jsonb NOT NULL,
+  messages jsonb NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now()
+);`;
+}
+var PostgresMemoryStore = class _PostgresMemoryStore {
+  constructor(client, tables, options) {
+    this.client = client;
+    this.tables = tables;
+    this.options = options;
+  }
+  client;
+  tables;
+  options;
+  kind = "postgres";
+  static async connect(options = {}) {
+    const client = options.client ?? await defaultPgClient(options.connectionString);
+    const tables = resolveTables(options);
+    const resolved = resolveOptions(options);
+    if (resolved.createIfMissing) {
+      await client.query(createPostgresMemorySchemaSql(options));
+    }
+    return new _PostgresMemoryStore(client, tables, resolved);
+  }
+  async load(context) {
+    const result = await this.client.query(
+      `SELECT m.message
+       FROM ${this.tables.messages} m
+       INNER JOIN ${this.tables.sessions} s ON s.id = m.memory_session_id
+       WHERE s.scope_key = $1
+       ORDER BY m.position ASC`,
+      [this.scopeKey(context)]
+    );
+    return result.rows.map((row) => this.messageFromValue(row.message));
+  }
+  async append(input) {
+    if (input.messages.length === 0) {
+      return;
+    }
+    const scopeKey = this.scopeKey(input.context);
+    await this.transaction(async (tx) => {
+      if (this.options.lock === "advisory") {
+        await tx.query("SELECT pg_advisory_xact_lock(hashtext($1))", [scopeKey]);
+      }
+      const session = await this.upsertSession(tx, input.context, scopeKey);
+      const last = await tx.query(
+        `SELECT position
+         FROM ${this.tables.messages}
+         WHERE memory_session_id = $1
+         ORDER BY position DESC
+         LIMIT 1`,
+        [session.id]
+      );
+      const start = Number(last.rows[0]?.position ?? -1);
+      await this.insertMessages(tx, session.id, input, start + 1);
+    });
+  }
+  async clear(context) {
+    await this.client.query(`DELETE FROM ${this.tables.sessions} WHERE scope_key = $1`, [
+      this.scopeKey(context)
+    ]);
+  }
+  async recordError(input) {
+    if (this.options.errors === "ignore") {
+      return;
+    }
+    const scopeKey = this.scopeKey(input.context);
+    await this.transaction(async (tx) => {
+      if (this.options.lock === "advisory") {
+        await tx.query("SELECT pg_advisory_xact_lock(hashtext($1))", [scopeKey]);
+      }
+      const session = await this.upsertSession(tx, input.context, scopeKey);
+      await tx.query(
+        `INSERT INTO ${this.tables.errors} (
+          memory_session_id,
+          run_id,
+          error,
+          messages
+        ) VALUES ($1, $2, $3::jsonb, $4::jsonb)`,
+        [
+          session.id,
+          input.runId,
+          JSON.stringify(serializeUnknownError(input.error)),
+          JSON.stringify(input.messages)
+        ]
+      );
+    });
+  }
+  async transaction(operation) {
+    const tx = await transactionClient(this.client);
+    try {
+      await tx.query("BEGIN");
+      const result = await operation(tx);
+      await tx.query("COMMIT");
+      return result;
+    } catch (error) {
+      await tx.query("ROLLBACK");
+      throw error;
+    } finally {
+      if (isTransactionClient(tx)) {
+        tx.release();
+      }
+    }
+  }
+  async upsertSession(client, context, scopeKey) {
+    const result = await client.query(
+      `INSERT INTO ${this.tables.sessions} (
+        scope_key,
+        session_id,
+        user_id,
+        metadata
+      ) VALUES ($1, $2, $3, $4::jsonb)
+      ON CONFLICT (scope_key) DO UPDATE SET
+        session_id = EXCLUDED.session_id,
+        user_id = EXCLUDED.user_id,
+        metadata = EXCLUDED.metadata,
+        updated_at = now()
+      RETURNING id`,
+      [scopeKey, context.sessionId, context.userId ?? null, JSON.stringify(metadata(context))]
+    );
+    const session = result.rows[0];
+    if (session === void 0) {
+      throw new Error("PostgresMemoryStore failed to upsert memory session.");
+    }
+    return session;
+  }
+  async insertMessages(client, memorySessionId, input, start) {
+    const values = input.messages.flatMap((message, index) => [
+      memorySessionId,
+      input.runId,
+      input.turn,
+      start + index,
+      message.role,
+      JSON.stringify(message)
+    ]);
+    const placeholders = input.messages.map((_, index) => {
+      const offset = index * 6;
+      return `($${offset + 1}, $${offset + 2}, $${offset + 3}, $${offset + 4}, $${offset + 5}, $${offset + 6}::jsonb)`;
+    });
+    await client.query(
+      `INSERT INTO ${this.tables.messages} (
+        memory_session_id,
+        run_id,
+        turn,
+        position,
+        role,
+        message
+      ) VALUES ${placeholders.join(", ")}`,
+      values
+    );
+  }
+  messageFromValue(value) {
+    const parsed = typeof value === "string" ? JSON.parse(value) : value;
+    return this.options.validateMessages ? parseMemoryMessage(parsed) : parsed;
+  }
+  scopeKey(context) {
+    if (typeof this.options.scope === "function") {
+      return this.options.scope(context);
+    }
+    return createPostgresMemoryScopeKey(context, this.options.scope);
+  }
+};
+function resolveOptions(options) {
+  return {
+    scope: options.scope,
+    errors: options.errors ?? "store",
+    validateMessages: options.validateMessages ?? true,
+    createIfMissing: options.createIfMissing ?? true,
+    lock: options.lock ?? "advisory"
+  };
+}
+function resolveTables(options) {
+  const prefix = options.tablePrefix ?? "anvia_";
+  return {
+    sessions: quoteQualifiedIdentifier(options.tableNames?.sessions ?? `${prefix}memory_sessions`),
+    messages: quoteQualifiedIdentifier(options.tableNames?.messages ?? `${prefix}memory_messages`),
+    errors: quoteQualifiedIdentifier(options.tableNames?.errors ?? `${prefix}memory_errors`),
+    messagesPositionIndex: quoteIdentifier(`${prefix}memory_messages_session_position_idx`)
+  };
+}
+function quoteQualifiedIdentifier(identifier) {
+  const parts = identifier.split(".");
+  if (parts.length === 0 || parts.some((part) => part.length === 0)) {
+    throw new Error(`Invalid Postgres identifier: ${identifier}`);
+  }
+  return parts.map(quoteIdentifier).join(".");
+}
+function quoteIdentifier(identifier) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(identifier)) {
+    throw new Error(`Invalid Postgres identifier: ${identifier}`);
+  }
+  return `"${identifier.replaceAll('"', '""')}"`;
+}
+async function transactionClient(client) {
+  if (isPool(client)) {
+    return client.connect();
+  }
+  return client;
+}
+function isPool(client) {
+  return "connect" in client && typeof client.connect === "function";
+}
+function isTransactionClient(client) {
+  return "release" in client && typeof client.release === "function";
+}
+async function defaultPgClient(connectionString) {
+  const pg = await import("pg");
+  return new pg.Pool(connectionString === void 0 ? {} : { connectionString });
+}
+function metadata(context) {
+  return context.metadata ?? {};
+}
+function metadataValue(metadata2, path) {
+  let current = metadata2;
+  for (const part of path.split(".")) {
+    if (!isJsonObject(current)) {
+      return void 0;
+    }
+    current = current[part];
+  }
+  return current;
+}
+function isJsonObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export {
+  PostgresMemoryStore,
+  createPostgresMemorySchemaSql,
+  createPostgresMemoryScopeKey,
+  createPostgresMemoryStore
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/message.ts","../src/store.ts"],"sourcesContent":["import type { JsonValue, Message } from \"@anvia/core\";\n\nexport function parseMemoryMessage(value: unknown): Message {\n  if (!isMemoryMessage(value)) {\n    throw new TypeError(\"Stored Postgres memory row does not contain a valid Anvia Message.\");\n  }\n  return value;\n}\n\nexport function isMemoryMessage(value: unknown): value is Message {\n  if (!isRecord(value) || typeof value.role !== \"string\") {\n    return false;\n  }\n\n  if (value.role === \"system\") {\n    return typeof value.content === \"string\";\n  }\n\n  if (value.role === \"user\" || value.role === \"assistant\" || value.role === \"tool\") {\n    return Array.isArray(value.content);\n  }\n\n  return false;\n}\n\nexport function serializeUnknownError(error: unknown): JsonValue {\n  if (error instanceof Error) {\n    return {\n      name: error.name,\n      message: error.message,\n      ...(error.stack === undefined ? {} : { stack: error.stack }),\n    };\n  }\n\n  if (isJsonValue(error)) {\n    return error;\n  }\n\n  return {\n    message: String(error),\n  };\n}\n\nfunction isJsonValue(value: unknown): value is JsonValue {\n  if (\n    value === null ||\n    typeof value === \"string\" ||\n    typeof value === \"number\" ||\n    typeof value === \"boolean\"\n  ) {\n    return Number.isFinite(value) || typeof value !== \"number\";\n  }\n\n  if (Array.isArray(value)) {\n    return value.every(isJsonValue);\n  }\n\n  return (\n    isRecord(value) && Object.values(value).every((item) => item === undefined || isJsonValue(item))\n  );\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n","import type { JsonObject, JsonValue, MemoryStore, Message } from \"@anvia/core\";\nimport type { MemoryAppendInput, MemoryContext, MemoryErrorInput } from \"@anvia/core/memory\";\nimport { parseMemoryMessage, serializeUnknownError } from \"./message.js\";\nimport type {\n  PostgresMemoryClientLike,\n  PostgresMemoryPoolLike,\n  PostgresMemorySchemaOptions,\n  PostgresMemoryScopeOptions,\n  PostgresMemoryStoreOptions,\n  PostgresMemoryTransactionClientLike,\n} from \"./types.js\";\n\nconst defaultScopeOptions: { includeUserId: boolean; metadataKeys: string[] } = {\n  includeUserId: true,\n  metadataKeys: [],\n};\n\ntype ResolvedPostgresMemoryStoreOptions = Required<\n  Pick<PostgresMemoryStoreOptions, \"createIfMissing\" | \"errors\" | \"lock\" | \"validateMessages\">\n> &\n  Pick<PostgresMemoryStoreOptions, \"scope\">;\n\ntype ResolvedPostgresMemoryTables = {\n  sessions: string;\n  messages: string;\n  errors: string;\n  messagesPositionIndex: string;\n};\n\ntype SessionRow = {\n  id: string;\n};\n\ntype PositionRow = {\n  position: number | string | null;\n};\n\ntype MessageRow = {\n  message: unknown;\n};\n\nexport async function createPostgresMemoryStore(\n  options: PostgresMemoryStoreOptions = {},\n): Promise<PostgresMemoryStore> {\n  return PostgresMemoryStore.connect(options);\n}\n\nexport function createPostgresMemoryScopeKey(\n  context: MemoryContext,\n  options: PostgresMemoryScopeOptions = {},\n): string {\n  const includeUserId = options.includeUserId ?? defaultScopeOptions.includeUserId;\n  const metadataKeys = options.metadataKeys ?? defaultScopeOptions.metadataKeys;\n  const values: JsonValue[] = [context.sessionId];\n\n  if (includeUserId) {\n    values.push(context.userId ?? null);\n  }\n\n  for (const key of metadataKeys) {\n    values.push(metadataValue(context.metadata, key) ?? null);\n  }\n\n  return JSON.stringify(values);\n}\n\nexport function createPostgresMemorySchemaSql(options: PostgresMemorySchemaOptions = {}): string {\n  const tables = resolveTables(options);\n  return `CREATE EXTENSION IF NOT EXISTS pgcrypto;\n\nCREATE TABLE IF NOT EXISTS ${tables.sessions} (\n  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),\n  scope_key text NOT NULL UNIQUE,\n  session_id text NOT NULL,\n  user_id text,\n  metadata jsonb NOT NULL DEFAULT '{}'::jsonb,\n  created_at timestamptz NOT NULL DEFAULT now(),\n  updated_at timestamptz NOT NULL DEFAULT now()\n);\n\nCREATE TABLE IF NOT EXISTS ${tables.messages} (\n  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),\n  memory_session_id uuid NOT NULL REFERENCES ${tables.sessions}(id) ON DELETE CASCADE,\n  run_id text NOT NULL,\n  turn integer NOT NULL,\n  position integer NOT NULL,\n  role text NOT NULL,\n  message jsonb NOT NULL,\n  created_at timestamptz NOT NULL DEFAULT now()\n);\n\nCREATE UNIQUE INDEX IF NOT EXISTS ${tables.messagesPositionIndex}\n  ON ${tables.messages}(memory_session_id, position);\n\nCREATE TABLE IF NOT EXISTS ${tables.errors} (\n  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),\n  memory_session_id uuid NOT NULL REFERENCES ${tables.sessions}(id) ON DELETE CASCADE,\n  run_id text NOT NULL,\n  error jsonb NOT NULL,\n  messages jsonb NOT NULL,\n  created_at timestamptz NOT NULL DEFAULT now()\n);`;\n}\n\nexport class PostgresMemoryStore implements MemoryStore {\n  readonly kind = \"postgres\";\n\n  private constructor(\n    private readonly client: PostgresMemoryClientLike,\n    private readonly tables: ResolvedPostgresMemoryTables,\n    private readonly options: ResolvedPostgresMemoryStoreOptions,\n  ) {}\n\n  static async connect(options: PostgresMemoryStoreOptions = {}): Promise<PostgresMemoryStore> {\n    const client = options.client ?? (await defaultPgClient(options.connectionString));\n    const tables = resolveTables(options);\n    const resolved = resolveOptions(options);\n\n    if (resolved.createIfMissing) {\n      await client.query(createPostgresMemorySchemaSql(options));\n    }\n\n    return new PostgresMemoryStore(client, tables, resolved);\n  }\n\n  async load(context: MemoryContext): Promise<Message[]> {\n    const result = await this.client.query(\n      `SELECT m.message\n       FROM ${this.tables.messages} m\n       INNER JOIN ${this.tables.sessions} s ON s.id = m.memory_session_id\n       WHERE s.scope_key = $1\n       ORDER BY m.position ASC`,\n      [this.scopeKey(context)],\n    );\n\n    return result.rows.map((row) => this.messageFromValue((row as MessageRow).message));\n  }\n\n  async append(input: MemoryAppendInput): Promise<void> {\n    if (input.messages.length === 0) {\n      return;\n    }\n\n    const scopeKey = this.scopeKey(input.context);\n\n    await this.transaction(async (tx) => {\n      if (this.options.lock === \"advisory\") {\n        await tx.query(\"SELECT pg_advisory_xact_lock(hashtext($1))\", [scopeKey]);\n      }\n\n      const session = await this.upsertSession(tx, input.context, scopeKey);\n      const last = await tx.query(\n        `SELECT position\n         FROM ${this.tables.messages}\n         WHERE memory_session_id = $1\n         ORDER BY position DESC\n         LIMIT 1`,\n        [session.id],\n      );\n      const start = Number(((last.rows[0] as PositionRow | undefined)?.position ?? -1) as number);\n      await this.insertMessages(tx, session.id, input, start + 1);\n    });\n  }\n\n  async clear(context: MemoryContext): Promise<void> {\n    await this.client.query(`DELETE FROM ${this.tables.sessions} WHERE scope_key = $1`, [\n      this.scopeKey(context),\n    ]);\n  }\n\n  async recordError(input: MemoryErrorInput): Promise<void> {\n    if (this.options.errors === \"ignore\") {\n      return;\n    }\n\n    const scopeKey = this.scopeKey(input.context);\n\n    await this.transaction(async (tx) => {\n      if (this.options.lock === \"advisory\") {\n        await tx.query(\"SELECT pg_advisory_xact_lock(hashtext($1))\", [scopeKey]);\n      }\n\n      const session = await this.upsertSession(tx, input.context, scopeKey);\n      await tx.query(\n        `INSERT INTO ${this.tables.errors} (\n          memory_session_id,\n          run_id,\n          error,\n          messages\n        ) VALUES ($1, $2, $3::jsonb, $4::jsonb)`,\n        [\n          session.id,\n          input.runId,\n          JSON.stringify(serializeUnknownError(input.error)),\n          JSON.stringify(input.messages),\n        ],\n      );\n    });\n  }\n\n  private async transaction<T>(\n    operation: (tx: PostgresMemoryClientLike) => Promise<T>,\n  ): Promise<T> {\n    const tx = await transactionClient(this.client);\n    try {\n      await tx.query(\"BEGIN\");\n      const result = await operation(tx);\n      await tx.query(\"COMMIT\");\n      return result;\n    } catch (error) {\n      await tx.query(\"ROLLBACK\");\n      throw error;\n    } finally {\n      if (isTransactionClient(tx)) {\n        tx.release();\n      }\n    }\n  }\n\n  private async upsertSession(\n    client: PostgresMemoryClientLike,\n    context: MemoryContext,\n    scopeKey: string,\n  ): Promise<SessionRow> {\n    const result = await client.query(\n      `INSERT INTO ${this.tables.sessions} (\n        scope_key,\n        session_id,\n        user_id,\n        metadata\n      ) VALUES ($1, $2, $3, $4::jsonb)\n      ON CONFLICT (scope_key) DO UPDATE SET\n        session_id = EXCLUDED.session_id,\n        user_id = EXCLUDED.user_id,\n        metadata = EXCLUDED.metadata,\n        updated_at = now()\n      RETURNING id`,\n      [scopeKey, context.sessionId, context.userId ?? null, JSON.stringify(metadata(context))],\n    );\n    const session = result.rows[0] as SessionRow | undefined;\n    if (session === undefined) {\n      throw new Error(\"PostgresMemoryStore failed to upsert memory session.\");\n    }\n    return session;\n  }\n\n  private async insertMessages(\n    client: PostgresMemoryClientLike,\n    memorySessionId: string,\n    input: MemoryAppendInput,\n    start: number,\n  ): Promise<void> {\n    const values = input.messages.flatMap((message, index) => [\n      memorySessionId,\n      input.runId,\n      input.turn,\n      start + index,\n      message.role,\n      JSON.stringify(message),\n    ]);\n    const placeholders = input.messages.map((_, index) => {\n      const offset = index * 6;\n      return `($${offset + 1}, $${offset + 2}, $${offset + 3}, $${offset + 4}, $${\n        offset + 5\n      }, $${offset + 6}::jsonb)`;\n    });\n\n    await client.query(\n      `INSERT INTO ${this.tables.messages} (\n        memory_session_id,\n        run_id,\n        turn,\n        position,\n        role,\n        message\n      ) VALUES ${placeholders.join(\", \")}`,\n      values,\n    );\n  }\n\n  private messageFromValue(value: unknown): Message {\n    const parsed = typeof value === \"string\" ? (JSON.parse(value) as unknown) : value;\n    return this.options.validateMessages ? parseMemoryMessage(parsed) : (parsed as Message);\n  }\n\n  private scopeKey(context: MemoryContext): string {\n    if (typeof this.options.scope === \"function\") {\n      return this.options.scope(context);\n    }\n    return createPostgresMemoryScopeKey(context, this.options.scope);\n  }\n}\n\nfunction resolveOptions(options: PostgresMemoryStoreOptions): ResolvedPostgresMemoryStoreOptions {\n  return {\n    scope: options.scope,\n    errors: options.errors ?? \"store\",\n    validateMessages: options.validateMessages ?? true,\n    createIfMissing: options.createIfMissing ?? true,\n    lock: options.lock ?? \"advisory\",\n  };\n}\n\nfunction resolveTables(options: PostgresMemorySchemaOptions): ResolvedPostgresMemoryTables {\n  const prefix = options.tablePrefix ?? \"anvia_\";\n  return {\n    sessions: quoteQualifiedIdentifier(options.tableNames?.sessions ?? `${prefix}memory_sessions`),\n    messages: quoteQualifiedIdentifier(options.tableNames?.messages ?? `${prefix}memory_messages`),\n    errors: quoteQualifiedIdentifier(options.tableNames?.errors ?? `${prefix}memory_errors`),\n    messagesPositionIndex: quoteIdentifier(`${prefix}memory_messages_session_position_idx`),\n  };\n}\n\nfunction quoteQualifiedIdentifier(identifier: string): string {\n  const parts = identifier.split(\".\");\n  if (parts.length === 0 || parts.some((part) => part.length === 0)) {\n    throw new Error(`Invalid Postgres identifier: ${identifier}`);\n  }\n  return parts.map(quoteIdentifier).join(\".\");\n}\n\nfunction quoteIdentifier(identifier: string): string {\n  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(identifier)) {\n    throw new Error(`Invalid Postgres identifier: ${identifier}`);\n  }\n  return `\"${identifier.replaceAll('\"', '\"\"')}\"`;\n}\n\nasync function transactionClient(\n  client: PostgresMemoryClientLike,\n): Promise<PostgresMemoryClientLike | PostgresMemoryTransactionClientLike> {\n  if (isPool(client)) {\n    return client.connect();\n  }\n  return client;\n}\n\nfunction isPool(client: PostgresMemoryClientLike): client is PostgresMemoryPoolLike {\n  return \"connect\" in client && typeof client.connect === \"function\";\n}\n\nfunction isTransactionClient(\n  client: PostgresMemoryClientLike,\n): client is PostgresMemoryTransactionClientLike {\n  return \"release\" in client && typeof client.release === \"function\";\n}\n\nasync function defaultPgClient(\n  connectionString: string | undefined,\n): Promise<PostgresMemoryPoolLike> {\n  const pg = await import(\"pg\");\n  return new pg.Pool(connectionString === undefined ? {} : { connectionString });\n}\n\nfunction metadata(context: MemoryContext): JsonObject {\n  return context.metadata ?? {};\n}\n\nfunction metadataValue(metadata: JsonObject | undefined, path: string): JsonValue | undefined {\n  let current: JsonValue | undefined = metadata;\n  for (const part of path.split(\".\")) {\n    if (!isJsonObject(current)) {\n      return undefined;\n    }\n    current = current[part];\n  }\n  return current;\n}\n\nfunction isJsonObject(value: JsonValue | undefined): value is JsonObject {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n"],"mappings":"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","names":["metadata"]}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@anvia/memory-postgres",
+  "version": "0.2.0",
+  "description": "Postgres-backed durable session memory store for Anvia.",
+  "author": "anvia",
+  "maintainer": "Indra Zulfi",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/anvia-hq/anvia",
+    "directory": "packages/memory-postgres"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "pg": "^8.22.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.9.1",
+    "@types/pg": "^8.15.6",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.8",
+    "@anvia/core": "0.12.3"
+  },
+  "peerDependencies": {
+    "@anvia/core": ">=0.12.0 <1.0.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --sourcemap --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}