Function: souledAgent()
souledAgent(
opts):Promise<SouledAgent>
Defined in: packages/agentos/src/api/souledAgent.ts:576
Create an agent whose long-term memory is its soul-file memory/ wiki.
When the soul resolves to a workspace directory, the wiki is wired end to end
(store + write-back + read_memory_page tool + prelude index.md). For inline
souls ({ content }) there is no workspace, so this falls back to a plain
agent and says so in one console.warn line.
Memory is kept per subject. A session turn is filed under the key of its subject, the user the session named or
else the session itself, the user's message and the reply alike, and it recalls that subject's memory and the
operator's pages, and nobody else's. A one-shot generate() or stream() names no user: nothing is filed for it,
it recalls the operator's pages alone, and one memory.one_shot_unfiled line an agent says so. With
SouledAgentOptions.sharedMemory every session that names no user, and every one-shot call, runs as one
user. Traces an earlier version filed under the agent's plain id stay in the store, are read by no turn, and are
counted in one memory.legacy_traces line at open. The store's folder, memory/.store/, gets a .gitignore holding
* when it has none; a file git tracked before stays tracked until the host removes it from the index.
Each stored turn records who spoke it in the trace's metadata (SPEAKER_METADATA_KEY), outside its text and its tags, so recall never matches a trace by its speaker; each recalled trace is sent as one record, with its speaker and its date, in a data block. The wiki compile's model calls go on the agent's route with its fallback settings, are checked against and charged to its spend budget, and are written to its usage ledger under the source SOULED_AGENT_COMPILE_SOURCE.
The wiki is compiled once a subject, from that subject's traces alone, into pages that are rows of the store and
never files under memory/; each subject has its own watermark. close() compiles the subjects its turns wrote
to, and agent.memory.compileWiki() every subject with new traces. A subject whose compile the spend budget
refuses is skipped with one memory.compile_skipped line: its traces wait for the next compile, and the other
subjects compile.
Three options say what is kept and where it goes. SouledAgentOptions.compile names the provider or model
the compile's calls go to, or turns the compile off (false: raw traces only, one memory.compile_skipped line at
open). SouledAgentOptions.memoryPolicy is asked once a session for the account the turn serves: off files
nothing and recalls the operator's pages alone, raw files and recalls and compiles no page, compiled is the
default. SouledAgentOptions.screen is given each text before it is filed and again before it is compiled.
Both hooks fail closed: a hook that throws, times out or answers anything else files nothing for that write
(memory.write_refused), and a compile it fails for does not run (memory.compile_skipped), its traces waiting
with their watermark where it was. A compile started in a process that served no turn of a subject has no policy
answer and no hook context for it: under a policy hook it is not compiled, and under a screen hook neither.
close() first closes the agent (with runtime: 'gmi' that stops its session turns), then waits, within one
deadline (see SouledAgentOptions.pendingWritesTimeoutMs), for the turns still running (a generate(), a
stream(), a session's send() or stream(), on either runtime; a stream whose signal aborted before anything was
read from it is not waited for, and on the default runtime a stream nobody reads and nobody aborts keeps the wait
until the deadline) and for the memory writes of its turns, then compiles the wiki, then closes the store. A turn or a write
still pending when the deadline passes is left out of the compile, and a write that reaches the store after it is
closed is not stored.
Parameters
opts
Agent options with a required soul.
Returns
Promise<SouledAgent>
A fully-wired Agent.
Throws
TypeError when sharedMemory is not { as, reason } with a user id that names someone and one of the two
reasons; nothing is opened.
Throws
Error when sharedMemory is set and the store already holds the memory of another user or session; the
store is closed first.
Throws
TypeError when memoryPolicy, screen or sharedMemory is set on an agent whose cognitive memory is on
(runtime: 'gmi' with cognition.memory, the full profile, or the memory option): the GMI keeps that memory
in a store of its own, which none of them reaches; nothing is opened.