Context Injection

Cortexa provides three levels of context injection, from manual to fully automatic.

Level 1: On-Demand (cortexa_context)

The agent calls cortexa_context when it needs prior knowledge:

cortexa_context({
  context: "fixing OAuth token refresh",
  project: "my-api",
  file_paths: ["src/auth/middleware.rs"]
})

Returns a brief grouped by thought type with multi-signal ranking:

• Semantic similarity (HNSW, O(log N))
• Keyword match (FTS5 BM25)
• Project boost (+15–20%)
• File-path boost (+10%)

Use max_chars to cap output for token-constrained contexts.

The project argument improves ranking; it is not a strict content boundary. Globally relevant results can still appear, and callers that require exact project isolation should not treat this legacy brief as an authorization filter. Foundry's Project memory mode uses a different contract: it removes retrieved vault items that are not attached to the selected project after the globally bounded candidate search.

Level 2: Zero-Prompt (sync-context)

Generate a .cortexa-context.md file that agents read automatically:

cortexa-cli sync-context MyProject --dir /path/to/project

This creates a markdown file with your most relevant decisions, architecture notes, patterns, and TODOs for that project. Claude Code, Cursor, and any agent that reads project files consumes it without needing to call any tool.

Recommended Setup

1. Add to .gitignore:

   .cortexa-context.md

2. Add a git hook (.git/hooks/post-checkout):

   #!/bin/sh
   cortexa-cli sync-context MyProject --dir . &

3. Or add to your shell profile:

   # Auto-sync context when entering a project directory
   cd() {
     builtin cd "$@"
     if [ -f "package.json" ] || [ -f "Cargo.toml" ]; then
       cortexa-cli sync-context "$(basename $PWD)" --dir . 2>/dev/null &
     fi
   }

Level 3: Agent-Triggered

Agents can call cortexa_sync_context via MCP to regenerate the file themselves:

cortexa_sync_context({
  project: "my-api",
  dir: "/home/user/projects/my-api"
})

This is useful at the start of a session or after making major decisions that future sessions should know about.

How Context Ranking Works

Results are ranked by a multi-signal score:

final_score = (1 - keyword_weight) × semantic_score
            + keyword_weight × bm25_score
            + project_boost     (if project matches)
            + file_path_boost   (if file paths overlap)

Default: 70% semantic, 30% keyword. Queries that look like identifiers (e.g., parse_thesis_json, AUTH_TOKEN) auto-boost keyword weight to 70%.

Token Budget Control

For agents with limited context windows, use max_chars:

cortexa_context({
  context: "...",
  max_chars: 4000
})

The brief stops adding items once the output exceeds the budget, showing "(budget exceeded, more items available)" for remaining categories.

These relevance and confidence signals are heuristics for ordering context. They are not calibrated probabilities that a memory is factually true.

Review traceable memory

When traceable context packets are enabled, a thought's detail view shows its retained source references and local review state. Mark reviewed records that you checked the current content. Dispute removes that revision from future packets. Replace with points an obsolete decision to a reviewed current capture in the same project, and Undo latest appends a reversal without deleting history. Every action requires a reason and checks the exact revision, so a concurrent edit must be reviewed again.

“Reviewed on this device” describes an explicit local action. It is not a team consensus or a probability that the content is true. Reviews apply to traceable context on this device. Legacy context and other devices may still return older decisions.