How It Works
Withmemory.procedures enabled, the memory manager can extract successful multi-tool sequences after runs and supply relevant procedures as context. Extraction uses a model. Suggestions do not force the Agent to follow a sequence and do not bypass tool policy.
Quick Start
This complete example exercises the store without a model or external service. Install@agentium/core@4.0.0, then run it in an ESM TypeScript project with tsx.
InMemoryStorage.close() removes its data. Substitute persistent storage when procedures must survive a restart.
Scope hierarchy (v2.3+)
The supported scopes remainuser, agent, tenant, and global. Reads union scopes accessible through the supplied caller fields. Writes choose one scope and require its matching owner field (userId, agentName, or tenantId); global records have no owner field. The host must verify those identifiers before calling the store.
Automatic extraction uses user scope. Explicitly sharing a record is an application decision. Storage scoping remains necessary when tenant isolation must cover shared Agent labels and direct store access.
Configuration
Agent configuration ismemory: { storage, procedures: true }, or procedures: { maxProcedures: 50 }. maxProcedures is the only option exposed by the unified ProceduresConfig in v4. There are no configurable minSteps, maxSteps, matchThreshold, autoExtract, or successThreshold fields.
The standalone ProcedureMemory constructor also accepts an optional extraction model. The host owns storage initialization and cleanup when using the store directly.
Procedure Structure
A record containsid, trigger, description, steps, successCount, lastUsed, createdAt, and scope/owner fields. A step contains toolName, argsSnapshot, and resultSummary. It does not contain embeddings, parameter-hint templates, or a failure counter.
Avoid storing credentials or user secrets in argument snapshots. Review records before promoting them to a broader scope.
How Procedures Are Learned
Extraction asks a model to identify successful sequences with at least two tool calls. It is background memory work, not a deterministic replay engine. Observe extraction failures and drain work before shutdown. For a guaranteed ordered operation, use a Workflow.Procedure Matching with suggestProcedure
Call suggestProcedure(caller, input) on ProcedureMemory. In v4, matching uses trigger/description words plus a bounded success-count contribution. It is not embedding similarity, and it does not check the supplied Agent’s available tools. The host or Agent must still decide whether the suggestion is relevant and executable.
The recall_procedure Tool
Enabling procedure memory exposes recall alongside the relevant memory tools. A recalled sequence remains guidance; validate every selected tool’s current arguments, ownership, grants, and approval requirements.
Full Example: Learning and Reusing
Use the offline example above to test ownership and matching first. Then enable procedures on a tool-using Agent, perform a representative successful run, wait for extraction to drain, and inspect saved records before testing recall in a later session. Keep the same verified user scope across those sessions.How Procedures Evolve
Saving another procedure with the same case-insensitive trigger in the same scope updates its steps/description and incrementssuccessCount. When capacity is reached, older lastUsed entries are removed. There is no automatic version history or rollback; retain application audit records if you need those guarantees.