The AI-native file format that gives every agent full project context before writing a line of code.

Cortex Protocol

The Cortex Protocol is a structured, file-based format that stores everything an AI agent needs to understand your project — your stack, architecture, past decisions, learned patterns, known risks, and ongoing reasoning.

It lives in a .cortex/ directory at your project root. Every agent reads it before starting work. Every decision gets recorded back into it.

Why It Exists

AI tools today start every session with zero context. You re-explain your project, your preferences, your past mistakes — every time. The Cortex Protocol fixes this by giving agents a persistent, machine-readable memory of your project.

What It Contains

ProjectDNA

Your project's fingerprint: languages, frameworks, databases, infrastructure, AI providers, build tools, architecture type (monorepo, microservices, etc.), entry points, boundaries, and data flow.

Timeline

An append-only reasoning ledger. Every decision, discovery, fix, refactor, experiment, failure, and learning gets recorded with confidence scores, references, and outcomes. Agents query the timeline to avoid repeating mistakes and to build on past successes.

SemanticGraph

A graph of code relationships — nodes represent files, functions, types, and concepts. Edges represent dependencies, imports, and semantic connections. Agents use this to understand blast radius before making changes.

SwarmManifest

When multiple agents work on one task, the SwarmManifest coordinates them: who's assigned to what, what strategy they're using (parallel, sequential, hierarchical, auction), budget limits (tokens, cost, time), file locks, and merge policies.

File Structure

.cortex/
  manifest.crtx     # ProjectDNA
  timeline.crtx      # Reasoning ledger
  graph.crtx          # Semantic graph
  swarm.crtx          # Active swarm state
  reasoning/
    task-abc.crtx     # Per-task reasoning traces

How to Use It

import { CortexIO, DNAManager, Timeline } from '@codmir/cortex';

const io = new CortexIO(process.cwd());
await io.init();

const dna = new DNAManager(io);
await dna.initialize({
  id: 'my-project',
  name: 'My App',
  purpose: 'Production web application',
  stack: {
    languages: ['TypeScript'],
    frameworks: ['Next.js', 'Tailwind'],
    databases: ['PostgreSQL'],
    infrastructure: ['Vercel', 'Railway'],
    aiProviders: ['anthropic', 'openai'],
    buildTools: ['turbo', 'tsup'],
  },
});

const timeline = new Timeline(io);
await timeline.record({
  agentId: 'agent-001',
  type: 'decision',
  action: 'Chose PostgreSQL over MongoDB',
  reasoning: 'Relational data model with strong consistency requirements',
  confidence: 0.95,
});

Learn More

• CortexIO API Reference — Read/write .cortex/ files
• DNAManager API Reference — Project intelligence encoding
• Timeline API Reference — Reasoning ledger
• SwarmProtocol API Reference — Multi-agent coordination
• Guide: Cortex Protocol — Step-by-step setup guide