@agents-js/memory-local

Local single-process MemoryProvider for agents-js (Bun runtime only — depends on bun:sqlite). Backed by a pluggable storage seam (sqlite by default) with an optional policy-gate hook.

Installation

bun add @agents-js/memory-local

API

Classes

• LocalMemoryProvider — Local, single-process MemoryProvider. Orchestrates the policy-gate seam, idempotency lookup, creator-only ACL, and optimistic-concurrency checks on top of an injected Storage backend (typically...
• SqliteStorage — sqlite-backed {Storage} impl. Uses bun:sqlite (a runtime built-in; no npm dependency). WAL is enabled so concurrent readers never block a writer, and synchronous = NORMAL trades a small crash-w...

Functions

• cloneRecord — Local deep-clone helper. Why this exists: -js/memory does not currently export a cloneRecord helper, but the sqlite storage impl needs to defensively clone records on the way out (so a caller m...
• migrate — Read PRAGMA user_version; if 0, apply {SCHEMA_DDL} and stamp currentVersion. If already equal, no-op. If greater than currentVersion, throw — refuse to open a file written by a newer binary. ...

Interfaces

• LocalMemoryProviderOptions
• MemoryPolicyGate — Optional policy hook injected into LocalMemoryProvider. Evaluated BEFORE the storage call; the provider lifts a deny (and, in v1, ask) into a MemoryAclError. The interactive "ask" variant...
• MemoryPolicyInput
• MemoryPolicyResult
• SqliteStorageOptions
• Storage — Storage seam used by LocalMemoryProvider. Public surface: external consumers can implement this interface to back the provider with their own durable storage (e.g. postgres, level, a remote KV) i...
• StoredRecord — Backend-stored record shape. Extends the public MemoryRecord with provider-internal fields (creator provenance, idempotency key) that are not exposed across the MemoryProvider boundary.
• StoredRecordPatch — Partial update payload accepted by the storage seam. Mirrors the caller-facing UpdateMemoryInput semantic: absent fields are untouched, present fields replace.

Types

• MemoryPolicyDecision
• MemoryPolicyOp
• UpdateRecordResult

Constants

• CURRENT_SCHEMA_VERSION — Bumped whenever the on-disk DDL changes incompatibly. The migration function stamps this into PRAGMA user_version after applying the DDL, and refuses to open a file whose stored version is newer ...
• noopPolicyGate — Default gate — always allows. Lets the provider work out of the box with no policy plumbing. Callers opt in to enforcement by supplying their own gate.
• SCHEMA_DDL — Canonical schema. CREATE TABLE IF NOT EXISTS makes the DDL safe to re-run; the migration function still only applies it on a fresh database (user_version = 0) so the per-process cost is one read....

Exports

• MemoryAclError
• MemoryRevisionConflictError
• type LocalMemoryProviderOptions
• type SqliteStorageOptions

Dependencies

• @agents-js/memory

License

MIT