Sync Context Files

The cortexa_sync_context tool generates a .cortexa-context.md file in your project directory — giving every AI agent instant access to your institutional memory without calling any MCP tool.

How It Works

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

This creates .cortexa-context.md containing your most relevant decisions, architecture notes, patterns, TODOs, and debug findings for that project — ranked by multi-signal relevance with a +20% project boost.

The file looks like:

<!-- Auto-generated by Cortexa — do not edit manually -->
<!-- Last updated: 2026-05-21 18:30 UTC -->
<!-- Project: MyProject -->

# Cortexa Context Brief
15 relevant items from your vault:

## Decisions
- [85%] Switched from Redis to DynamoDB for session storage (a1b2c3d4) [project:MyProject]
- [72%] Auth middleware uses constant-time comparison for tokens (e5f6g7h8)

## Architecture
- [78%] Service mesh with Envoy sidecars for inter-service auth (i9j0k1l2)

## TODOs
- [65%] Migrate legacy OAuth tokens to the new format (m3n4o5p6)

Why It Matters

Without this file, agents start every session blank. With it:

• Claude Code reads it as part of its project context
• Cursor sees it when scanning the working directory
• Any agent that reads markdown files gets your decisions for free

No tool call needed. No prompt needed. Just knowledge, injected automatically.

Three Ways to Generate

CLI

cortexa-cli sync-context MyProject --dir .

MCP Tool

{
  "name": "cortexa_sync_context",
  "arguments": {
    "project": "MyProject",
    "dir": "/absolute/path/to/project"
  }
}

HTTP API

curl -X POST http://127.0.0.1:7373/api/sync-context \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"project": "MyProject", "dir": "/path/to/project"}'

Recommended Setup

1. Add to .gitignore

.cortexa-context.md

The file is machine-generated and user-specific — don't commit it.

2. Git Hook (post-checkout)

Create .git/hooks/post-checkout:

#!/bin/sh
cortexa-cli sync-context "$(basename $PWD)" --dir . 2>/dev/null &

Every time you switch branches, the context file refreshes.

3. Shell Integration

Add to your .bashrc / .zshrc:

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

Every time you cd into a project, context syncs in the background.

4. Agent-Triggered

Agents can regenerate the file themselves:

cortexa_sync_context({ project: "MyProject", dir: "/path/to/project" })

Useful at session start or after capturing major decisions.

How Ranking Works

The sync-context tool uses the same multi-signal search as cortexa_context:

1. Semantic similarity — HNSW approximate nearest neighbors
2. Keyword match — FTS5 BM25 scoring
3. Project boost (+20%) — items captured from the same project rank higher
4. File-path boost (+5%) — items mentioning project files rank higher

Results are grouped by thought type (Decisions first, then Architecture, Patterns, Debug, TODOs) and capped at 15 items for a concise brief.