Recall & Context Loading

Relevant source files

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

• src/api/recall.ts
• src/mcp/server.ts
• README.md
• paper/drafts/cortex-v2-4-technical-note.md
• benchmarks/cogbench/client.ts
• src/reconsolidation/index.ts

Recall & Context Loading is the system responsible for retrieving relevant information from the CORTEX memory graph and formatting it into a context window for AI agents. Unlike standard vector search, this system uses a hybrid scoring mechanism and token-budget awareness to ensure agents receive high-priority, semantically relevant, and temporally valid context without exceeding prompt limits.

The system facilitates "Recall" as a specialized retrieval mode that greedily selects memory nodes and cognitive artifacts (decisions, insights, etc.) based on a ranked score until a specified token budget is reached. This process ensures that the most critical "living" context is loaded into the agent's working memory at the start of or during a session.
Sources: README.md:144-152, src/api/recall.ts:32-34

Hybrid Scoring & Retrieval Logic

CORTEX utilizes a 7-factor hybrid scoring system to rank memories during lookup. This scoring prevents the "every Tuesday meeting looks the same" problem by incorporating metadata beyond simple vector similarity.

The linear combination used for scoring includes the following weights:

• 0.45 — Cosine Similarity: Semantic relevance of the embedding.
• 0.18 — Text Match: Exact substring or keyword hit.
• 0.12 — Recency: Exponential decay with a 30-day half-life.
• 0.10 — Resonance: Ebbinghaus stability-adjusted score.
• 0.10 — Emotional Boost: Salience based on valence/arousal vectors.
• 0.05 — Priority Boost: Manual weighting (P0 critical to P4 ephemeral).

Sources: paper/drafts/cortex-v2-4-technical-note.md:85-94, src/mcp/server.ts:74-98

The Retrieval Flow

The following diagram illustrates the sequence of operations when an agent requests context via the cortex_recall tool or the /api/v1/recall endpoint.

Recall Configuration and Constraints

The RecallResult interface defines the structure of the returned context, which separates "Relevant Memories" from "Recent Cognitive Artifacts."
Sources: src/api/recall.ts:10-24

API Parameters

Parameter	Type	Default	Description
query	string	REQUIRED	The search string to find relevant context.
agentId	string	REQUIRED	The external ID of the agent session.
tokenBudget	number	4000	Max tokens for the combined context window.

Sources: src/api/recall.ts:35-37, src/mcp/server.ts:162-167

Context Allocation Logic

The system applies specific heuristics to fill the token budget:

1. Memory Budget: 80% of the total tokenBudget is reserved for memory nodes.
2. Artifact Budget: 20% is reserved for recent cognitive artifacts (decisions, insights).
3. Truncation: If a high-scoring memory (Score > 0.6) cannot fit entirely, the system includes a 400-character truncated snippet to maximize information density.
4. Formatting: The output is returned as a Markdown-formatted string with clear H2 and H3 headings.

Sources: src/api/recall.ts:55-100, src/mcp/server.ts:200-225

Labile Windows and Reconsolidation

A critical side effect of the Recall process is the opening of a "labile window." Based on neuroscience principles (Nader et al. 2000), when a memory is retrieved, it becomes malleable for a short duration.

• Trigger: Accessing memories via cortex_recall or cortex_search updates the last_recalled_at timestamp.
• Window Duration: 1 hour.
• Function: Within this window, the cortex_reconsolidate tool can be used to update or correct a memory's content. If the window expires, the memory "restabilizes" and cannot be modified without a new recall event.

Session Initialization

At the start of every session, the cortex_init tool is invoked to perform a "boot sequence." This is a specialized form of context loading that provides the agent with high-level system awareness rather than just query-specific facts.

The cortex_init response includes:

• System Status: Active memory counts, synapse counts, and average resonance.
• Last Dream Cycle: Results from the most recent maintenance phase.
• Active Entities: A list of the top 15 most-mentioned entities across all active memories.
• Top Context: The top 20 memories globally, prioritized by critical status (P0/P1) and high resonance.

Sources: src/mcp/server.ts:241-332

Summary

Recall & Context Loading transforms CORTEX from a static database into a living cognitive system. By combining hybrid 7-factor scoring with strict token management, it provides AI agents with the most relevant "working context" while simultaneously managing the biological-inspired lifecycle of memories through labile windows and reconsolidation. This ensures that agents remain grounded in recent events while maintaining the ability to evolve their internal knowledge base.
Sources: README.md:14-36, paper/drafts/cortex-v2-4-technical-note.md:20-30