@absolutejs/agent-memory 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AbsoluteJS
+
+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,12 @@
+# @absolutejs/agent-memory
+
+Durable, provider-neutral memory for agents with tenant/user/agent/run scopes,
+mandatory provenance digests, taint-compatible metadata, per-operation policy,
+expiration, deletion, subject erasure, optimistic versions, and idempotent writes.
+
+Values pass through an injected codec so production deployments can use KMS or
+envelope encryption. Retrieval indexes are adapters: pgvector, a vector service,
+or custom search can rank IDs without becoming the source of record. Retrieved
+records remain labeled memory data; this package never promotes them to trusted
+instructions. Use `validateWrite` with `@absolutejs/agent-trust` to reject poisoned
+or inappropriately sensitive memories before persistence.

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./types";
+export * from "./memory-store";
+export * from "./postgres";
+export * from "./service";

package/dist/index.js

@@ -0,0 +1,235 @@
+// @bun
+// src/memory-store.ts
+var scopeKey = (scope) => JSON.stringify([
+  scope.tenantId,
+  scope.namespace,
+  scope.userId ?? "",
+  scope.agentId ?? "",
+  scope.runId ?? ""
+]);
+var createMemoryAgentMemoryStore = () => {
+  const rows = new Map;
+  const requests = new Map;
+  const keyOf = (scope, key) => `${scopeKey(scope)}:${key}`;
+  return {
+    put: async ({ record, requestId, expectedVersion }) => {
+      const previousId = requests.get(requestId);
+      if (previousId)
+        return structuredClone([...rows.values()].find((row) => row.id === previousId));
+      const key = keyOf(record.scope, record.key);
+      const existing = rows.get(key);
+      if (expectedVersion !== undefined && existing?.version !== expectedVersion)
+        throw new Error("Agent memory version conflict");
+      if (existing && expectedVersion === undefined)
+        throw new Error("expectedVersion is required to replace memory");
+      rows.set(key, structuredClone(record));
+      requests.set(requestId, record.id);
+      return structuredClone(record);
+    },
+    get: async (scope, key) => structuredClone(rows.get(keyOf(scope, key))),
+    getByIds: async (ids) => [...rows.values()].filter((row) => ids.includes(row.id)).map((row) => structuredClone(row)),
+    list: async (scope, limit) => [...rows.values()].filter((row) => scopeKey(row.scope) === scopeKey(scope)).sort((a, b) => b.updatedAt.localeCompare(a.updatedAt)).slice(0, limit).map((row) => structuredClone(row)),
+    delete: async (scope, key) => rows.delete(keyOf(scope, key)),
+    eraseSubject: async ({ tenantId, userId }) => {
+      const matched = [...rows].filter(([, row]) => row.scope.tenantId === tenantId && (row.scope.userId === userId || row.createdBy.userId === userId));
+      for (const [key] of matched)
+        rows.delete(key);
+      return matched.length;
+    },
+    prune: async (now, limit) => {
+      const matched = [...rows].filter(([, row]) => row.expiresAt && row.expiresAt <= now).slice(0, limit);
+      for (const [key] of matched)
+        rows.delete(key);
+      return matched.length;
+    }
+  };
+};
+// src/postgres.ts
+var safe = (value) => {
+  if (!/^[a-z_][a-z0-9_]*$/i.test(value))
+    throw new Error("Invalid SQL namespace");
+  return value;
+};
+var agentMemoryPostgresSchemaSql = (schema = "agent_memory") => {
+  const ns = safe(schema);
+  return `CREATE SCHEMA IF NOT EXISTS ${ns}; CREATE TABLE IF NOT EXISTS ${ns}.records (id text PRIMARY KEY, tenant_id text NOT NULL, namespace text NOT NULL, user_id text NOT NULL DEFAULT '', agent_id text NOT NULL DEFAULT '', run_id text NOT NULL DEFAULT '', memory_key text NOT NULL, version integer NOT NULL, expires_at timestamptz, document jsonb NOT NULL, updated_at timestamptz NOT NULL, UNIQUE (tenant_id,namespace,user_id,agent_id,run_id,memory_key)); CREATE INDEX IF NOT EXISTS agent_memory_expiry_idx ON ${ns}.records (expires_at) WHERE expires_at IS NOT NULL; CREATE INDEX IF NOT EXISTS agent_memory_subject_idx ON ${ns}.records (tenant_id,user_id); CREATE TABLE IF NOT EXISTS ${ns}.requests (request_id text PRIMARY KEY, record_id text NOT NULL REFERENCES ${ns}.records(id) ON DELETE CASCADE, created_at timestamptz NOT NULL DEFAULT now());`;
+};
+var parts = (scope) => [
+  scope.tenantId,
+  scope.namespace,
+  scope.userId ?? "",
+  scope.agentId ?? "",
+  scope.runId ?? ""
+];
+var createPostgresAgentMemoryStore = ({
+  client,
+  schema = "agent_memory"
+}) => {
+  const ns = safe(schema);
+  const document = (row) => row ? typeof row.document === "string" ? JSON.parse(row.document) : row.document : undefined;
+  return {
+    put: ({ record, requestId, expectedVersion }) => client.transaction(async (tx) => {
+      await tx.query(`SELECT pg_advisory_xact_lock(hashtextextended($1,0))`, [
+        requestId
+      ]);
+      const prior = document((await tx.query(`SELECT r.document FROM ${ns}.requests q JOIN ${ns}.records r ON r.id=q.record_id WHERE q.request_id=$1`, [requestId])).rows[0]);
+      if (prior)
+        return prior;
+      const values = [...parts(record.scope), record.key];
+      const result = expectedVersion === undefined ? await tx.query(`INSERT INTO ${ns}.records (id,tenant_id,namespace,user_id,agent_id,run_id,memory_key,version,expires_at,document,updated_at) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9::timestamptz,$10::jsonb,$11::timestamptz) RETURNING document`, [
+        record.id,
+        ...values,
+        record.version,
+        record.expiresAt ?? null,
+        JSON.stringify(record),
+        record.updatedAt
+      ]) : await tx.query(`UPDATE ${ns}.records SET version=$8,expires_at=$9::timestamptz,document=$10::jsonb,updated_at=$11::timestamptz WHERE tenant_id=$1 AND namespace=$2 AND user_id=$3 AND agent_id=$4 AND run_id=$5 AND memory_key=$6 AND version=$7 RETURNING document`, [
+        ...values,
+        expectedVersion,
+        record.version,
+        record.expiresAt ?? null,
+        JSON.stringify(record),
+        record.updatedAt
+      ]);
+      const saved = document(result.rows[0]);
+      if (!saved)
+        throw new Error("Agent memory version conflict");
+      await tx.query(`INSERT INTO ${ns}.requests (request_id,record_id) VALUES ($1,$2)`, [requestId, saved.id]);
+      return saved;
+    }),
+    get: async (scope, key) => document((await client.query(`SELECT document FROM ${ns}.records WHERE tenant_id=$1 AND namespace=$2 AND user_id=$3 AND agent_id=$4 AND run_id=$5 AND memory_key=$6`, [...parts(scope), key])).rows[0]),
+    getByIds: async (ids) => ids.length ? (await client.query(`SELECT document FROM ${ns}.records WHERE id = ANY($1::text[])`, [ids])).rows.map((row) => document(row)) : [],
+    list: async (scope, limit) => (await client.query(`SELECT document FROM ${ns}.records WHERE tenant_id=$1 AND namespace=$2 AND user_id=$3 AND agent_id=$4 AND run_id=$5 ORDER BY updated_at DESC LIMIT $6`, [...parts(scope), limit])).rows.map((row) => document(row)),
+    delete: async (scope, key) => (await client.query(`DELETE FROM ${ns}.records WHERE tenant_id=$1 AND namespace=$2 AND user_id=$3 AND agent_id=$4 AND run_id=$5 AND memory_key=$6 RETURNING id`, [...parts(scope), key])).rows.length === 1,
+    eraseSubject: async ({ tenantId, userId }) => (await client.query(`DELETE FROM ${ns}.records WHERE tenant_id=$1 AND (user_id=$2 OR document->'createdBy'->>'userId'=$2) RETURNING id`, [tenantId, userId])).rows.length,
+    prune: async (now, limit) => (await client.query(`DELETE FROM ${ns}.records WHERE id IN (SELECT id FROM ${ns}.records WHERE expires_at <= $1::timestamptz ORDER BY expires_at LIMIT $2 FOR UPDATE SKIP LOCKED) RETURNING id`, [now, limit])).rows.length
+  };
+};
+// src/service.ts
+var identityCodec = {
+  encode: async (value) => structuredClone(value),
+  decode: async (value) => structuredClone(value)
+};
+var assertScope = (actor, scope) => {
+  if (actor.tenantId !== scope.tenantId)
+    throw new Error("Cross-tenant agent memory access denied");
+};
+var createAgentMemory = ({
+  store,
+  authorize,
+  codec = identityCodec,
+  index,
+  validateWrite,
+  now = Date.now,
+  id = () => crypto.randomUUID()
+}) => {
+  const decode = async (stored) => ({
+    ...stored,
+    value: await codec.decode(stored.encodedValue, {
+      scope: stored.scope,
+      key: stored.key
+    })
+  });
+  const permitted = async (operation, actor, scope, record) => {
+    assertScope(actor, scope);
+    if (!await authorize({
+      operation,
+      actor,
+      scope,
+      ...record ? { record } : {}
+    }))
+      throw new Error(`Agent memory ${operation} denied`);
+  };
+  return {
+    put: async (input) => {
+      await permitted("write", input.actor, input.scope);
+      if (!input.provenance.digest)
+        throw new Error("Memory provenance digest is required");
+      if (input.expiresAt && !Number.isFinite(Date.parse(input.expiresAt)))
+        throw new Error("Invalid memory expiration");
+      const existing = await store.get(input.scope, input.key);
+      const timestamp = new Date(now()).toISOString();
+      const record = {
+        id: existing?.id ?? id(),
+        key: input.key,
+        scope: structuredClone(input.scope),
+        value: structuredClone(input.value),
+        provenance: structuredClone(input.provenance),
+        sensitivity: input.sensitivity ?? "internal",
+        version: (existing?.version ?? 0) + 1,
+        createdAt: existing?.createdAt ?? timestamp,
+        updatedAt: timestamp,
+        ...input.expiresAt ? { expiresAt: input.expiresAt } : {},
+        createdBy: structuredClone(input.actor)
+      };
+      if (validateWrite && !await validateWrite(record))
+        throw new Error("Agent memory write failed trust validation");
+      const stored = {
+        ...record,
+        encodedValue: await codec.encode(record.value, {
+          scope: record.scope,
+          key: record.key
+        })
+      };
+      delete stored.value;
+      const saved = await store.put({
+        record: stored,
+        requestId: input.requestId,
+        ...input.expectedVersion !== undefined ? { expectedVersion: input.expectedVersion } : {}
+      });
+      const decoded = await decode(saved);
+      await index?.upsert(decoded);
+      return decoded;
+    },
+    get: async (actor, scope, key) => {
+      await permitted("read", actor, scope);
+      const stored = await store.get(scope, key);
+      if (!stored || stored.expiresAt && stored.expiresAt <= new Date(now()).toISOString())
+        return;
+      const record = await decode(stored);
+      await permitted("read", actor, scope, record);
+      return record;
+    },
+    search: async (actor, scope, query, limit = 10) => {
+      await permitted("search", actor, scope);
+      const ranked = index ? await index.search({ scope, query, limit }) : (await store.list(scope, Math.min(limit, 100))).map((row, position) => ({ id: row.id, score: 1 / (position + 1) }));
+      const rows = await store.getByIds(ranked.map((item) => item.id));
+      const byId = new Map(rows.map((row) => [row.id, row]));
+      const output = [];
+      for (const item of ranked) {
+        const row = byId.get(item.id);
+        if (!row || row.expiresAt && row.expiresAt <= new Date(now()).toISOString())
+          continue;
+        const record = await decode(row);
+        await permitted("read", actor, scope, record);
+        output.push({ record, score: item.score });
+      }
+      return output;
+    },
+    delete: async (actor, scope, key) => {
+      await permitted("delete", actor, scope);
+      const row = await store.get(scope, key);
+      const removed = await store.delete(scope, key);
+      if (removed && row)
+        await index?.remove(row.id);
+      return removed;
+    },
+    eraseSubject: async (actor, userId) => {
+      const scope = { tenantId: actor.tenantId, namespace: "*", userId };
+      await permitted("erase", actor, scope);
+      const count = await store.eraseSubject({
+        tenantId: actor.tenantId,
+        userId
+      });
+      await index?.eraseSubject?.({ tenantId: actor.tenantId, userId });
+      return count;
+    },
+    prune: (limit = 1000) => store.prune(new Date(now()).toISOString(), limit)
+  };
+};
+export {
+  createPostgresAgentMemoryStore,
+  createMemoryAgentMemoryStore,
+  createAgentMemory,
+  agentMemoryPostgresSchemaSql
+};

package/dist/manifest.d.ts

@@ -0,0 +1 @@
+export declare const manifest: import("@absolutejs/manifest").PackageManifest<unknown, never>;

package/dist/manifest.js

@@ -0,0 +1,23 @@
+// @bun
+// src/manifest.ts
+import { defineManifest } from "@absolutejs/manifest";
+import { Type } from "@sinclair/typebox";
+var manifest = defineManifest()({
+  contract: 2,
+  identity: {
+    name: "@absolutejs/agent-memory",
+    category: "data",
+    tagline: "Give agents useful memory without giving memory authority.",
+    description: "Scoped durable provenance-aware agent memory with per-operation authorization, retention, subject erasure, encrypted codecs, trust validation, and pluggable retrieval indexes.",
+    docsUrl: "https://github.com/absolutejs/agent-memory",
+    accent: "#8b5cf6"
+  },
+  settings: Type.Object({}),
+  slots: {},
+  implements: [],
+  tools: {},
+  wiring: []
+});
+export {
+  manifest
+};

package/dist/manifest.json

@@ -0,0 +1,19 @@
+{
+	"contract": 2,
+	"identity": {
+		"name": "@absolutejs/agent-memory",
+		"category": "data",
+		"tagline": "Give agents useful memory without giving memory authority.",
+		"description": "Scoped durable provenance-aware agent memory with per-operation authorization, retention, subject erasure, encrypted codecs, trust validation, and pluggable retrieval indexes.",
+		"docsUrl": "https://github.com/absolutejs/agent-memory",
+		"accent": "#8b5cf6"
+	},
+	"settings": {
+		"type": "object",
+		"properties": {}
+	},
+	"slots": {},
+	"implements": [],
+	"wiring": [],
+	"tools": {}
+}

package/dist/memory-store.d.ts

@@ -0,0 +1,2 @@
+import type { AgentMemoryStore } from "./types";
+export declare const createMemoryAgentMemoryStore: () => AgentMemoryStore;

package/dist/postgres.d.ts

@@ -0,0 +1,15 @@
+import type { AgentMemoryStore } from "./types";
+export type AgentMemorySqlResult<Row> = {
+    rows: Row[];
+};
+export type AgentMemorySqlTransaction = {
+    query<Row = Record<string, unknown>>(sql: string, params?: readonly unknown[]): Promise<AgentMemorySqlResult<Row>>;
+};
+export type AgentMemorySqlClient = AgentMemorySqlTransaction & {
+    transaction<Value>(work: (tx: AgentMemorySqlTransaction) => Promise<Value>): Promise<Value>;
+};
+export declare const agentMemoryPostgresSchemaSql: (schema?: string) => string;
+export declare const createPostgresAgentMemoryStore: ({ client, schema, }: {
+    client: AgentMemorySqlClient;
+    schema?: string;
+}) => AgentMemoryStore;

package/dist/service.d.ts

@@ -0,0 +1,30 @@
+import type { AgentMemoryActor, AgentMemoryAuthorizer, AgentMemoryCodec, AgentMemoryProvenance, AgentMemoryRecord, AgentMemoryScope, AgentMemorySearchIndex, AgentMemoryStore } from "./types";
+export declare const createAgentMemory: ({ store, authorize, codec, index, validateWrite, now, id, }: {
+    store: AgentMemoryStore;
+    authorize: AgentMemoryAuthorizer;
+    codec?: AgentMemoryCodec;
+    index?: AgentMemorySearchIndex;
+    validateWrite?: (record: AgentMemoryRecord) => boolean | Promise<boolean>;
+    now?: () => number;
+    id?: () => string;
+}) => {
+    put: (input: {
+        actor: AgentMemoryActor;
+        scope: AgentMemoryScope;
+        key: string;
+        value: unknown;
+        provenance: AgentMemoryProvenance;
+        sensitivity?: AgentMemoryRecord["sensitivity"];
+        expiresAt?: string;
+        requestId: string;
+        expectedVersion?: number;
+    }) => Promise<AgentMemoryRecord>;
+    get: (actor: AgentMemoryActor, scope: AgentMemoryScope, key: string) => Promise<AgentMemoryRecord | undefined>;
+    search: (actor: AgentMemoryActor, scope: AgentMemoryScope, query: string, limit?: number) => Promise<{
+        record: AgentMemoryRecord;
+        score: number;
+    }[]>;
+    delete: (actor: AgentMemoryActor, scope: AgentMemoryScope, key: string) => Promise<boolean>;
+    eraseSubject: (actor: AgentMemoryActor, userId: string) => Promise<number>;
+    prune: (limit?: number) => Promise<number>;
+};

package/dist/types.d.ts

@@ -0,0 +1,87 @@
+export type AgentMemoryScope = {
+    tenantId: string;
+    namespace: string;
+    userId?: string;
+    agentId?: string;
+    runId?: string;
+};
+export type AgentMemoryActor = {
+    tenantId: string;
+    userId: string;
+    agentId: string;
+    delegationId?: string;
+};
+export type AgentMemoryProvenance = {
+    source: string;
+    sourceType: "user" | "agent" | "tool" | "web" | "file" | "memory" | "system";
+    retrievedAt: string;
+    digest: string;
+    parentDigests?: string[];
+    proof?: unknown;
+    taints?: string[];
+};
+export type AgentMemoryRecord<Value = unknown> = {
+    id: string;
+    key: string;
+    scope: AgentMemoryScope;
+    value: Value;
+    provenance: AgentMemoryProvenance;
+    sensitivity: "public" | "internal" | "personal" | "secret";
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+    expiresAt?: string;
+    createdBy: AgentMemoryActor;
+};
+export type StoredAgentMemoryRecord = Omit<AgentMemoryRecord, "value"> & {
+    encodedValue: unknown;
+};
+export type AgentMemoryOperation = "read" | "write" | "search" | "delete" | "erase";
+export type AgentMemoryAuthorizer = (input: {
+    operation: AgentMemoryOperation;
+    actor: AgentMemoryActor;
+    scope: AgentMemoryScope;
+    record?: AgentMemoryRecord;
+}) => boolean | Promise<boolean>;
+export type AgentMemoryCodec = {
+    encode(value: unknown, context: {
+        scope: AgentMemoryScope;
+        key: string;
+    }): Promise<unknown>;
+    decode(value: unknown, context: {
+        scope: AgentMemoryScope;
+        key: string;
+    }): Promise<unknown>;
+};
+export type AgentMemoryStore = {
+    put(input: {
+        record: StoredAgentMemoryRecord;
+        requestId: string;
+        expectedVersion?: number;
+    }): Promise<StoredAgentMemoryRecord>;
+    get(scope: AgentMemoryScope, key: string): Promise<StoredAgentMemoryRecord | undefined>;
+    getByIds(ids: readonly string[]): Promise<StoredAgentMemoryRecord[]>;
+    list(scope: AgentMemoryScope, limit: number): Promise<StoredAgentMemoryRecord[]>;
+    delete(scope: AgentMemoryScope, key: string): Promise<boolean>;
+    eraseSubject(input: {
+        tenantId: string;
+        userId: string;
+    }): Promise<number>;
+    prune(now: string, limit: number): Promise<number>;
+};
+export type AgentMemorySearchIndex = {
+    upsert(record: AgentMemoryRecord): Promise<void>;
+    remove(id: string): Promise<void>;
+    search(input: {
+        scope: AgentMemoryScope;
+        query: string;
+        limit: number;
+    }): Promise<Array<{
+        id: string;
+        score: number;
+    }>>;
+    eraseSubject?(input: {
+        tenantId: string;
+        userId: string;
+    }): Promise<void>;
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@absolutejs/agent-memory",
+  "version": "0.1.0",
+  "description": "Scoped durable provenance-aware memory with authorization, retention, erasure, encryption seams, and pluggable retrieval for AI agents.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/absolutejs/agent-memory.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "absolutejs": {
+    "manifestContract": 2
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./manifest": {
+      "types": "./dist/manifest.d.ts",
+      "import": "./dist/manifest.js"
+    },
+    "./manifest.json": "./dist/manifest.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "format": "prettier --write \"./**/*.{ts,json,md,yml}\"",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "build": "rm -rf dist && bun build src/index.ts src/manifest.ts --outdir dist --target=bun --external @absolutejs/manifest --external @sinclair/typebox && tsc -p tsconfig.build.json && absolute-manifest emit",
+    "check:package": "bun run typecheck && bun run test && bun run build"
+  },
+  "dependencies": {
+    "@absolutejs/manifest": "^0.2.0",
+    "@sinclair/typebox": "^0.34.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "prettier": "3.5.3",
+    "typescript": "5.8.3"
+  }
+}