Procedural Memory

Relevant source files

The following files were used as context for generating this wiki page:

• src/procedural/index.ts
• src/api/procedural.ts
• src/procedural/types.ts
• src/mcp/server.ts
• README.md
• REFERENCES.md
• benchmarks/cogbench/tasks/procedural-learning.ts

Procedural Memory stores and retrieves skill, habit, and workflow knowledge separately from episodic memory. Unlike episodic memory, which records specific experiences, procedural memory captures "how to do things." These memories do not decay with time, strengthen through repeated execution, and are retrieved primarily by task context.

The biological basis for this module maps to the basal ganglia and cerebellum, distinguishing it from the hippocampal-dependent episodic memory. In CORTEX, this system allows agents to develop proficiencies over time, refining repeatable processes and heuristics based on success rates.

Sources: src/procedural/index.ts:1-12, src/procedural/types.ts:1-19, README.md:92-94, REFERENCES.md:143-150

Architecture and Data Model

Procedural Memory is implemented as a specialized storage layer within the PostgreSQL database. Each entry, defined by the ProceduralMemory interface, tracks its execution history and proficiency level.

Procedural Memory Object structure

Field	Type	Description
id	number	Unique identifier for the procedural memory.
name	string	Short name for the skill or workflow.
description	string	Detailed instructions on how to execute the procedure.
proceduralType	ProceduralType	The category: skill, workflow, pattern, preference, or heuristic.
triggerContext	string	The specific conditions or tasks that trigger this memory.
steps	string[]	Ordered list of execution steps or key principles.
proficiency	ProficiencyLevel	Growth stage: novice, competent, proficient, or expert.
executionCount	number	Total times this procedure has been applied.
successRate	number	Calculated as successCount / executionCount.
version	number	Incremental version number tracking refinements.

Sources: src/procedural/types.ts:37-67, src/procedural/index.ts:145-155

Procedural Types and Proficiency

The system categorizes procedural knowledge into five distinct types:

• Skill: Capabilities like writing outreach emails.
• Workflow: Multi-step processes like client onboarding.
• Pattern: Recognized situational responses.
• Preference: User-specific formatting or interaction choices.
• Heuristic: Rules of thumb for decision-making.

Sources: src/procedural/types.ts:22-29

Procedural Workflow

The following diagram illustrates the lifecycle of a procedural memory, from creation through execution and refinement.

The system utilizes a feedback loop where repeated successful execution leads to proficiency upgrades.
Sources: src/procedural/index.ts:141-175, benchmarks/cogbench/tasks/procedural-learning.ts:17-26

Retrieval Mechanisms

Retrieval uses a multi-strategy approach to find the most relevant procedure for a given task context.

1. Trigger Match: Uses ILIKE text matching to check if the task context matches a defined triggerContext.
2. Semantic Match: Performs a vector search using cosine similarity on the embedded description, name, and steps.
3. Domain Match: Checks for overlaps in domainTags.

Proficiency Advancement Rules

The recordExecution function automatically updates an agent's proficiency based on their track record.

New Proficiency	Execution Requirement	Success Rate Requirement
Expert	≥ 20 executions	≥ 90%
Proficient	≥ 10 executions	≥ 80%
Competent	≥ 3 executions	≥ 60%
Novice	< 3 executions	N/A

Sources: src/procedural/index.ts:178-200, benchmarks/cogbench/tasks/procedural-learning.ts:184-192

API and Tool Integration

The Procedural Memory module is exposed via a REST API and MCP (Model Context Protocol) tools for agent interaction.

MCP Tools

• cortex_skill_store: Creates a new procedural memory. It embeds the combined text of the name, description, and steps for future semantic retrieval.
• cortex_skill_retrieve: Searches for relevant procedures before starting a task.
• cortex_skill_executed: Records the outcome (success/failure) of a skill application to update proficiency.
• cortex_skill_refine: Updates the steps or description of a skill, incrementing its version and re-generating embeddings.

Sources: src/mcp/server.ts:639-724, src/procedural/index.ts:36-65

REST Endpoints

Endpoint	Method	Action
/api/v1/procedural	GET	Lists all active procedural memories for an agent.
/api/v1/procedural	POST	Stores a new skill, workflow, or pattern.
/api/v1/procedural/retrieve	POST	Finds procedures matching a specific taskContext.
/api/v1/procedural/:id/execute	POST	Updates execution counts and success rates.
/api/v1/procedural/:id	PATCH	Refines an existing procedure and increments version.

Sources: src/api/procedural.ts:15-135

Refinement and Versioning

Refinement occurs when an agent discovers a better way to perform a task. The refineProcedural function allows updating the description, steps, triggerContext, or domainTags. When a memory is refined, the system:

1. Increments the version number.
2. Generates a new text string combining the updated fields.
3. Calculates and stores a new embedding for semantic search.

Sources: src/procedural/index.ts:223-268, src/api/procedural.ts:124-133

Procedural Memory provides a persistent capability layer that ensures agents become more efficient and reliable through practice, distinguishing itself as a functional "basal ganglia" within the CORTEX architecture.