@arnilo/prism-memory

Optional working memory and semantic recall for Prism agents.

Install explicitly. This package is not included in profile bundles until a size/use review. Ordinary Prism sessions do not require a vector backend.

Install

npm install @arnilo/prism-memory @arnilo/prism

PostgreSQL/pgvector support uses the package pg dependency. Live adapter tests require PRISM_TEST_POSTGRES_URL and the vector extension.

Usage

import { createAgent } from "@arnilo/prism";
import { createHashEmbedder, createMemory } from "@arnilo/prism-memory";

const memory = createMemory({
  tenantId: "t1",
  resourceId: "user-ada",
  threadId: "thread-1",
  embedder: createHashEmbedder(), // replace with a host-owned production embedder
  workingMemoryTemplate: "Name: {{name}}; Format: {{preferences.format}}",
  schema: {
    type: "object",
    properties: {
      name: { type: "string" },
      preferences: {
        type: "object",
        properties: { format: { type: "string" } },
        required: ["format"],
        additionalProperties: false,
      },
    },
    required: ["name"],
    additionalProperties: false,
  },
});

await memory.updateWorking({ name: "Ada", preferences: { format: "concise" } });
await memory.remember({
  entries: [{ id: "m1", text: "Prefers concise answers" }],
}); // indexes asynchronously by default

const recalled = await memory.recall("preferred response format", { topK: 5, messageRange: 1 });

const agent = createAgent({
  // ...provider/model
  context: [memory.createContextProvider()],
});

API surface

| Export | Role | | --- | --- | | createMemory | Facade for working memory + semantic recall | | Embedder / VectorStore / WorkingMemoryStore | Narrow package-owned contracts (RAG reuses embed/vector) | | createHashEmbedder | Deterministic offline embedder for tests/demos | | assertFiniteVector | Reject empty, non-number, NaN, Infinity, or wrong-dimension vectors before a custom store | | createMemoryVectorStore / createMemoryWorkingStore | In-memory reference adapters | | createPostgresMemoryStores | PostgreSQL/pgvector production path | | runMemoryConformance | Shared network-free conformance helper | | createContextProvider / createWorkingMemoryProcessor | Existing context seam + opt-in update helper | | setConsent / correct / forget / applyRetention | Consent lifecycle: grant/revoke visibility, re-embed corrections, real deletes, bounded retention batches | | exportMemory / rebuildIndex | Exact-identity, redacted consented export pages; abortable/resumable bounded re-embedding | | listByThread / countByThread | Optional bounded-store methods required for export/rebuild and retention respectively |

Security

• tenantId and resourceId are mandatory on every write/query/delete; semantic operations also require threadId.
• Memory text/metadata are redacted when secrets / redactor are configured.
• Injected context is inert text only — no tools or permissions.
• Cross-tenant and cross-thread recall is denied.
• Consent (0.0.14): records carry consent { source, scope, visible }; recall() drops revoked/invisible entries at assembly time (direct recall and createContextProvider injection), and requireConsent strict mode also drops consent-less entries.
• exportMemory({ identity, cursor? }) requires exact tenant/resource/thread identity and emits only explicitly consented visible records, redacted and capped at 100 entries / 4 MiB / 10 seconds by default (200 / 32 MiB / 60 seconds hard). rebuildIndex({ cursor? }) re-embeds one stable page (32 default / 128 hard) and returns nextCursor for host-owned resume.
• Embedder output, in-memory upserts/queries, PostgreSQL/pgvector parameters, and export/rebuild pages accept only non-empty finite number vectors; NaN, ±Infinity, non-numbers, and wrong configured dimensions fail before scoring, SQL, response, or re-indexing.

See Working and semantic memory.