Skip to main content
Procedural memory saves a tool sequence as a suggested plan. The next run can use that plan, but it must still authorize and execute each action. A stored procedure is not an executable workflow, a grant, or proof that a new request is eligible for an effect.

How It Works

With memory.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.
The tool names describe a stored plan; this example does not invoke those tools. InMemoryStorage.close() removes its data. Substitute persistent storage when procedures must survive a restart.

Scope hierarchy (v2.3+)

The supported scopes remain user, 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 is memory: { 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 contains id, 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 increments successCount. 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.