MemoryProvider
Long-term memory storage behind save_memory, search_memory and forget_memory.
A provider only stores and searches: the framework issues bindings, checks scope, bounds and logs every call, and presents hits as untrusted reference. Build one with local_memory() or an adapter factory.
Properties
writeEffect / write_effectEffectClassThe effect class of save_memory and forget_memory with this provider. Absent: unguarded. idempotent requires dedup_window_ms: the provider dedups on the key within it.
dedupWindowMs / dedup_window_msPosIntHow long, in milliseconds, the provider dedups a write on its key. Required when write_effect is idempotent; otherwise leave it out. local_memory keeps keys forever.
Methods
remember
Store one record in the scope and return its id and version. The same key with the same record is a no-op that returns the same reference; the same key with a different record is invalid.
remember(scope: Scope, record: MemoryRecord, key: string): Promise<Result<RecordRef>>scopeScoperequiredThe scope to store the record in, issued by the host. See Scope.
recordMemoryRecordrequiredThe record to store, binding included. Store the binding as given. See MemoryRecord.
keystringrequiredThe write's idempotency key (the save_memory call's effect key). Dedup on it: a retry after a crash sends the same key.
Returns an error value with one of these codes: unavailable, timeout, invalid, scope_violation.
recall
Return the records in the scope that best match a query, best first. Return only records from this scope; the framework drops and audits any other.
recall(scope: Scope, query: string, options?: {
k?: PosInt;
}): Promise<Result<readonly MemoryHit[]>>scopeScoperequiredThe scope to search, issued by the host. See Scope.
querystringrequiredThe search text, as the model wrote it in search_memory.
kPosIntdefault 5The most hits to return, a positive integer. search_memory passes the model's k (1 to 20, 5 when it gives none), and the framework also caps the total hit text at 16 KB.
Returns an error value with one of these codes: unavailable, timeout, invalid, scope_violation.
forget
Delete one record from the scope. Forgetting a record twice succeeds; a record that isn't in the scope is invalid.
forget(scope: Scope, id: string, key: string): Promise<Result<void>>scopeScoperequiredThe scope the record is in, issued by the host. See Scope.
idstringrequiredThe record's id, as remember or recall returned it.
keystringrequiredThe delete's idempotency key (the forget_memory call's effect key). A retry sends the same key.
Returns an error value with one of these codes: unavailable, timeout, invalid, scope_violation.