PostgresStmAdapter
Defined in: packages/memory-stm/src/adapters/postgres-stm.adapter.ts:65
Postgres-backed short-term memory adapter.
Stores STM records as rows in the shared memories table with
type='short-term' and expiresAt set — the schema has carried both
columns (plus @@index([expiresAt])) since the baseline migration, so no
migration is needed. This replaces the Redis-backed MemoryStmService:
STM survives restarts, and both tiers live in one queryable store.
Semantics intentionally mirror the existing adapters:
- UUID ids (parity with the Redis service;
memoryIdSchemaaccepts them). accessCountand the stored full-TTL window (ttl) live in themetadataJSON, the same conventionMemoryLtmServiceuses foraccessCount/importance.- Expiry is enforced by filtering on read (
expiresAt > now()); expired rows are opportunistically deleted on touch and bulk-removed bysweepExpired()(scheduled by the mcp-server’s StmSweepService). update()preservesexpiresAtunless a newttlis explicitly provided (the WP2-T3/D4 preserve-by-default behavior).expectedVersionupdates are a true compare-and-set: the version guard is part of the UPDATE’s WHERE clause, closing the read-compare-set race the Redis implementation documented as deferred.- Embeddings are generated best-effort and stored on the row; STM rows are NOT upserted into the vector index (parity with both prior adapters — promotion to LTM is what indexes a memory for semantic recall).
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new PostgresStmAdapter(
prisma,embeddingsService?):PostgresStmAdapter
Defined in: packages/memory-stm/src/adapters/postgres-stm.adapter.ts:69
Parameters
Section titled “Parameters”prisma
Section titled “prisma”embeddingsService?
Section titled “embeddingsService?”Returns
Section titled “Returns”PostgresStmAdapter
Methods
Section titled “Methods”clear()
Section titled “clear()”clear(
userId,organizationId?):Promise<number>
Defined in: packages/memory-stm/src/adapters/postgres-stm.adapter.ts:379
Delete every personal (or org-scoped, when organizationId is given)
short-term memory for a user. Returns the number of removed rows.
Parameters
Section titled “Parameters”userId
Section titled “userId”string
organizationId?
Section titled “organizationId?”string
Returns
Section titled “Returns”Promise<number>
count()
Section titled “count()”count(
userId,options?):Promise<number>
Defined in: packages/memory-stm/src/adapters/postgres-stm.adapter.ts:367
Count short-term memories for a user with optional tag/scope filtering.
Parameters
Section titled “Parameters”userId
Section titled “userId”string
options?
Section titled “options?”organizationId?
Section titled “organizationId?”string
scope?
Section titled “scope?”string
string[]
Returns
Section titled “Returns”Promise<number>
create()
Section titled “create()”create(
input):Promise<StmMemory>
Defined in: packages/memory-stm/src/adapters/postgres-stm.adapter.ts:79
Create a new short-term memory.
Parameters
Section titled “Parameters”content
Section titled “content”string = contentSchema
metadata?
Section titled “metadata?”Record<string, unknown> = metadataSchema
organizationId?
Section titled “organizationId?”string = ...
scope?
Section titled “scope?”string = ...
string[] = ...
number = ttlSchema
userId
Section titled “userId”string = userIdSchema
Returns
Section titled “Returns”Promise<StmMemory>
delete()
Section titled “delete()”delete(
userId,memoryId,organizationId?,scope?):Promise<void>
Defined in: packages/memory-stm/src/adapters/postgres-stm.adapter.ts:242
Delete a short-term memory. A scope mismatch is treated as not-found so a caller bound to one namespace cannot delete another’s memory.
Parameters
Section titled “Parameters”userId
Section titled “userId”string
memoryId
Section titled “memoryId”string
organizationId?
Section titled “organizationId?”string
scope?
Section titled “scope?”string
Returns
Section titled “Returns”Promise<void>
extendTtl()
Section titled “extendTtl()”extendTtl(
userId,memoryId,additionalSeconds,organizationId?):Promise<StmMemory>
Defined in: packages/memory-stm/src/adapters/postgres-stm.adapter.ts:351
Extend a memory’s TTL by additionalSeconds (new total = remaining +
additional, validated against the TTL bounds).
Parameters
Section titled “Parameters”userId
Section titled “userId”string
memoryId
Section titled “memoryId”string
additionalSeconds
Section titled “additionalSeconds”number
organizationId?
Section titled “organizationId?”string
Returns
Section titled “Returns”Promise<StmMemory>
findById()
Section titled “findById()”findById(
userId,memoryId,organizationId?,scope?):Promise<StmMemory>
Defined in: packages/memory-stm/src/adapters/postgres-stm.adapter.ts:121
Retrieve a short-term memory by ID. Bumps accessCount (best-effort) so
the consolidation policy can identify frequently-read memories.
Parameters
Section titled “Parameters”userId
Section titled “userId”string
memoryId
Section titled “memoryId”string
organizationId?
Section titled “organizationId?”string
scope?
Section titled “scope?”string
Returns
Section titled “Returns”Promise<StmMemory>
findCandidates()
Section titled “findCandidates()”findCandidates(
threshold,userId?):Promise<StmMemory[]>
Defined in: packages/memory-stm/src/adapters/postgres-stm.adapter.ts:396
Find short-term memories with accessCount >= threshold for a user (or
globally when userId is omitted). Used by the consolidation job to
identify promotion candidates.
Parameters
Section titled “Parameters”threshold
Section titled “threshold”number
userId?
Section titled “userId?”string
Returns
Section titled “Returns”Promise<StmMemory[]>
getTtl()
Section titled “getTtl()”getTtl(
userId,memoryId,organizationId?):Promise<number>
Defined in: packages/memory-stm/src/adapters/postgres-stm.adapter.ts:329
Get the remaining TTL (in seconds) for a memory. Missing and expired memories both surface as not-found (parity with Redis TTL=-2).
Parameters
Section titled “Parameters”userId
Section titled “userId”string
memoryId
Section titled “memoryId”string
organizationId?
Section titled “organizationId?”string
Returns
Section titled “Returns”Promise<number>
list()
Section titled “list()”list(
userId,options?):Promise<PaginatedResult<StmMemory>>
Defined in: packages/memory-stm/src/adapters/postgres-stm.adapter.ts:285
List short-term memories for a user with cursor pagination and filtering.
The cursor contract matches the prior adapters: '0' is the start
sentinel; endCursor is '0' when there are no further pages.
Parameters
Section titled “Parameters”userId
Section titled “userId”string
options?
Section titled “options?”Partial<ListStmOptionsData> = {}
Returns
Section titled “Returns”Promise<PaginatedResult<StmMemory>>
promote()
Section titled “promote()”promote(
userId,memoryId,organizationId?):Promise<StmMemory>
Defined in: packages/memory-stm/src/adapters/postgres-stm.adapter.ts:423
Promotion hand-off: return the source memory so callers can chain into the LTM service, which performs the durable transfer.
Parameters
Section titled “Parameters”userId
Section titled “userId”string
memoryId
Section titled “memoryId”string
organizationId?
Section titled “organizationId?”string
Returns
Section titled “Returns”Promise<StmMemory>
sweepExpired()
Section titled “sweepExpired()”sweepExpired():
Promise<number>
Defined in: packages/memory-stm/src/adapters/postgres-stm.adapter.ts:432
Bulk-delete expired STM rows. Correctness never depends on this (every
read filters on expiresAt); it is hygiene that keeps the table small.
Scheduled by the mcp-server’s StmSweepService.
Returns
Section titled “Returns”Promise<number>
update()
Section titled “update()”update(
userId,memoryId,input,organizationId?,scope?):Promise<StmMemory>
Defined in: packages/memory-stm/src/adapters/postgres-stm.adapter.ts:157
Update a short-term memory. Preserves expiresAt unless ttl is
explicitly provided. When expectedVersion is set the write is a true
compare-and-set on the version column.
Parameters
Section titled “Parameters”userId
Section titled “userId”string
memoryId
Section titled “memoryId”string
content?
Section titled “content?”string = ...
expectedVersion?
Section titled “expectedVersion?”number = ...
Optimistic-concurrency guard (WP2 T4). When set, the update fails with
StmVersionConflictError unless it matches the stored version. Optional so
legacy callers keep last-write-wins.
metadata?
Section titled “metadata?”Record<string, unknown> = metadataSchema
string[] = tagsSchema
number = ttlSchema
organizationId?
Section titled “organizationId?”string
scope?
Section titled “scope?”string
Returns
Section titled “Returns”Promise<StmMemory>