cortex

name	cortex
description	Automatic session tracking and memory system for Claude Code. Activates when working in git repositories to track file changes, commits, and session context. Creates .cortex_log.md (session history), .cortex_status.json (current state), and .cortex_handoff.md (next steps) for session continuity across conversations. Use when needing persistent memory, session handoffs, or work history tracking.
allowed-tools	Read, Write, Bash, Grep, Glob

Cortex - Session Orchestration & Universal Logging

Cortex is an automatic memory system that traces all work across sessions and enables skills to communicate with each other.

What Cortex Provides

1. Automatic session tracing - Tracks all file changes, git operations, and major events
2. Agent handoffs - Seamless context transfer between sessions
3. Inter-skill communication - Python API for skills to share data and patterns
4. Pattern detection - Analyzes work patterns to recommend new skills (via Synapse)

Core Files Generated

Cortex automatically maintains three files in your project root:

• .cortex_log.md - Human-readable session history with detailed narrative
• .cortex_status.json - Machine-readable current state and metrics
• .cortex_handoff.md - Quick start guide for next session

These files are automatically updated throughout your work session.

How It Works

Automatic Tracing

Cortex runs automatically via git hooks. Every time you:

• Make file changes
• Commit code
• Complete a task

Cortex updates the memory files with context about what happened and why.

Agent Handoffs

When starting a new session, Claude reads .cortex_handoff.md to understand:

• What was done in the last session
• Current repository state
• Priority next steps
• Recent work context

Inter-Skill Communication

Skills can use Cortex's Python API to communicate:

from cortex_api import add_cortex_event, get_cortex_memory, get_pattern_analysis

# Record an event
add_cortex_event("api_call", "Called GitHub API", {
    "endpoint": "/repos/user/repo",
    "status": 200
})

# Query memory
recent_events = get_cortex_memory(filter_type="api_call", limit=10)

# Analyze patterns (used by Synapse)
patterns = get_pattern_analysis(days=7, threshold=5)

See API_REFERENCE.md for complete documentation.

Installation

Run the installation script to set up git hooks:

cd .claude/skills/cortex/scripts
./install.sh

This configures Cortex to automatically track your work.

Usage

Manual Session Tracing

To manually update Cortex files:

python3 .claude/skills/cortex/scripts/trace_session.py

Manual Handoff Generation

To generate a handoff document:

python3 .claude/skills/cortex/scripts/handoff_generator.py

Using Cortex API in Your Skills

1. Import the API:

   from cortex_api import add_cortex_event, get_cortex_memory
   

2. Record events during your skill's operation

3. Query patterns to inform decisions

4. Cortex handles all file locking and persistence

Integration with Synapse

Cortex's pattern analysis powers Synapse automatic skill generation:

1. Cortex tracks recurring patterns (API calls, data processing, etc.)
2. Synapse queries Cortex for patterns above a threshold
3. Synapse automatically generates skills when patterns reach critical frequency
4. New skills use Cortex API to record their own events

This creates a self-improving system where skills emerge from actual usage patterns.

Files and Scripts

Scripts

• trace_session.py - Updates .cortex_log.md and .cortex_status.json
• handoff_generator.py - Creates .cortex_handoff.md
• cortex_api.py - Python API for inter-skill communication
• install.sh - Sets up git hooks

References

• API_REFERENCE.md - Complete Cortex API documentation
• WORKFLOWS.md - Common Cortex usage patterns
• MULTI_LLM.md - Using Cortex with GPT, Gemini, etc.

Best Practices

1. Let it run automatically - Don't manually trace unless needed
2. Check .cortex_handoff.md at session start - Quick context refresh
3. Use Cortex API in custom skills - Enables automatic pattern detection
4. Commit Cortex files with your work - Preserves memory across machines

Multi-LLM Support

Cortex works with Claude Code, GPT, Gemini, and other CLI-based LLMs. The memory files use universal markdown and JSON formats.

See MULTI_LLM.md for LLM-specific integration guides.

---

Cortex is the foundation of DeepSynth's self-improving skills system.