@agents-js/memory

Library-agnostic write-side memory primitive for agents-js. Defines MemoryProvider, actor/scope/record types, and a conformance harness for backend implementations.

Installation

bun add @agents-js/memory

API

Classes

• InMemoryProvider — Reference provider — all capabilities = true. Lives in the package so the conformance harness has a known-good target. Consumers MAY use it as a test fixture; not intended for production storage.
• MemoryAclError — Thrown by providers when actor lacks permission to act on scope.
• MemoryRevisionConflictError — Thrown by providers when expectedRevision doesn't match current.

Functions

• createMockActor
• runProviderConformanceTests — Drop-in conformance suite. v1 has no read surface, so cross-record visibility tests are deferred to v2 — the suite only exercises what is observable through saveMemory, updateMemory, `deleteMem...

Interfaces

• ConformanceOptions — Conformance harness arguments. Pass describe, it, and expect directly from bun:test / vitest / jest — keeps the package framework-agnostic via dependency injection.
• DeleteMemoryInput
• InMemoryProviderOptions
• MemoryActor — Caller principal. Every primitive operation carries one. The provider uses this to enforce scope ACL (if it implements ACL) and to populate record provenance. Future versions MAY add more principal...
• MemoryProvider — Provider contract. Consumers implement this against the storage backend of their choice (in-process map, key-value store, document database, etc.) and pass the implementation to the runtime composi...
• MemoryRecord — Canonical record shape returned by save/update. Providers MUST populate all required fields; optional fields are present iff the provider's capabilities advertise support.
• ProviderCapabilities — Capability discovery — consumers can probe provider behavior without hard-coding backend assumptions. Providers MUST return this from capabilities().
• SaveMemoryInput
• UpdateMemoryInput

Types

• MemoryScope — Where a memory entry is visible. Caller resolves identity before calling — there is no "self" sentinel. The provider treats the scope as opaque for storage and as input to ACL when ACL is supported.
• MemoryType — Open enum. Recommended initial subset; providers MAY accept additional type strings, but consumers SHOULD pick from this list when possible so cross-provider queries (via fetchContext) can filter c...

Exports

• type InMemoryProviderOptions

Import paths

The API section above lists every documented export across both the package's main entry and its /testing subpath. Real consumer imports are split between them — picking the wrong path is a compile error, so it pays to know which symbol lives where.

Main entry — @agents-js/memory — runtime types and the provider contract (always available, zero runtime deps):

import {
  type MemoryActor,
  type MemoryScope,
  type MemoryType,
  type MemoryRecord,
  type MemoryProvider,
  type SaveMemoryInput,
  type UpdateMemoryInput,
  type DeleteMemoryInput,
  type ProviderCapabilities,
  MemoryAclError,
  MemoryRevisionConflictError,
} from "@agents-js/memory";

Testing subpath — @agents-js/memory/testing — conformance harness, reference provider, and helpers (test-time only; not intended for production code paths):

import {
  runProviderConformanceTests,
  type ConformanceOptions,
  InMemoryProvider,
  type InMemoryProviderOptions,
  createMockActor,
} from "@agents-js/memory/testing";

The conformance harness takes describe, it, and expect directly from any compatible framework (bun:test, vitest, jest):

import { describe, expect, it } from "bun:test";
import {
  InMemoryProvider,
  runProviderConformanceTests,
} from "@agents-js/memory/testing";

runProviderConformanceTests({
  describe,
  it,
  expect,
  makeProvider: () => new InMemoryProvider(),
});

License

MIT