Skip to main content

Type Alias: SouledAgent

SouledAgent = Agent & object

Defined in: packages/agentos/src/api/souledAgent.ts:465

Return type of souledAgent: an Agent with its backing Memory store exposed as memory, so callers can fold conversation into the wiki mid-session via await agent.memory.compileWiki(). memory and the members below are present whenever the soul resolves to a workspace directory; they are absent for inline souls that fall back to a plain agent.

Type Declaration​

memory?​

optional memory: Memory

applyTombstones()?​

optional applyTombstones(): Promise<ForgetMemoryReport[]>

Applies the tombstones again, as every open does: brings the store's ledger up to date from its copy, then deletes again whatever the store holds of a forgotten user or session. For a restore runbook, and for a schedule when several processes share one store on PostgreSQL.

Returns​

Promise<ForgetMemoryReport[]>

One report a subject deleted again; none on a store that holds nothing of a forgotten subject.

correctUserMemory()?​

optional correctUserMemory(userId, correction): Promise<{ correctionTraceId: string; deleted: number; pagesDeleted: number; }>

Corrects one person's memory: deletes the named traces for good, files text as a trace tagged correction, deletes each page built from a deleted trace and has the next compile build it again from the traces that are left. It rejects, and changes nothing, when any id is not one of that person's live traces.

Parameters​

userId​

string

correction​
text​

string

traceIds​

readonly string[]

Returns​

Promise<{ correctionTraceId: string; deleted: number; pagesDeleted: number; }>

How many traces and pages it deleted, and the id of the correction's trace.

Throws​

TypeError when userId, the trace ids or the text is missing.

exportUserMemory()?​

optional exportUserMemory(userId): Promise<UserMemoryExport>

One person's memory as JSON: their conversation traces (id, time, speaker, text, tags) and their compiled pages (id, summary, updated, sources, body), read from their own scope alone. Operator pages, other people's memory and a gmi() session's history are not in it; a forgotten person's export is empty.

Parameters​

userId​

string

Returns​

Promise<UserMemoryExport>

Throws​

TypeError when userId is not a non-empty string.

forgetUser()?​

optional forgetUser(userId, options?): Promise<ForgetMemoryReport>

Deletes one person's memory from this agent's store for good and keeps it deleted: it waits for the person's pending writes (up to pendingWritesTimeoutMs), records a tombstone, deletes their traces, document chunks, compiled pages and registry row, writes the vector index again, and clears the history of the sessions this handle holds open for them. With a learning layer, the layer's own forgetUser runs first. linkedSessions names the anonymous sessions the host has tied to the person: each is deleted the same way.

Parameters​

userId​

string

options?​
linkedSessions?​

readonly string[]

Returns​

Promise<ForgetMemoryReport>

One report for the user and the linked sessions: each store with reached and a count or a reason, the pages deleted and those that failed, drained, pendingAtDeadline and complete. It never holds the user's id or any text.

Throws​

TypeError when userId, or an entry of linkedSessions, is not a non-empty string, or holds a NUL or a lone surrogate, so no memory key can be built from it; nothing is deleted and no tombstone is written.

sweepRetention()?​

optional sweepRetention(): Promise<{ pages: number; scopes: number; traces: number; }>

Deletes for good what the agent's retention no longer keeps: each subject's traces older than its period, and the pages compiled from them (whole, or rebuilt from the traces that are left with pages: 'rebuild'). close() runs it too. Without retention it deletes nothing.

Returns​

Promise<{ pages: number; scopes: number; traces: number; }>

How many traces and pages it deleted, and how many subjects it removed from the registry.