The AI-native file format that gives every agent full project context.

Cortex Protocol

The Cortex Protocol is a structured file format that lives in a .cortex/ directory at the root of your project. It captures everything an AI agent needs to understand your codebase: architecture, constraints, past decisions, and coordination state. When 10,000 agents work on your project, the Cortex Protocol is how they share context without repeating mistakes.

The .cortex/ Directory

.cortex/
  manifest.crtx      # ProjectDNA — your codebase fingerprint
  timeline.crtx       # Append-only reasoning ledger
  graph.crtx          # SemanticGraph — code relationships
  swarm.crtx          # SwarmManifest — multi-agent coordination
  reasoning/          # Per-agent reasoning chains

Every .crtx file has a standard envelope:

interface CortexFile<T> {
  header: {
    cortex: 1;
    type: 'dna' | 'timeline' | 'graph' | 'swarm' | 'reasoning';
    project: string;
    created: number;
    updated: number;
    checksum: string;
  };
  data: T;
}

ProjectDNA -- Your Codebase Fingerprint

manifest.crtx contains the invisible knowledge that senior developers carry in their heads: tech stack, architecture boundaries, constraints, learned patterns, and risk zones.

interface ProjectDNA {
  version: 1;
  project: { id: string; name: string; purpose: string; created: number; updated: number };
  stack: StackFingerprint;
  architecture: ArchitectureMap;
  constraints: ProjectConstraint[];
  patterns: LearnedPattern[];
  risks: RiskZone[];
  owner: { style: string; preferences: string[] };
}

Initialize with DNAManager

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

const io = new CortexIO('/path/to/project');
await io.init();

const dna = new DNAManager(io);

await dna.initialize({
  id: 'my-project',
  name: 'My Application',
  purpose: 'E-commerce platform with AI-powered search',
  stack: {
    languages: ['TypeScript', 'SQL'],
    frameworks: ['Next.js', 'Prisma', 'tRPC'],
    databases: ['PostgreSQL', 'Redis'],
    infrastructure: ['Vercel', 'Railway'],
    aiProviders: ['Anthropic', 'OpenAI'],
    buildTools: ['turbo', 'pnpm', 'tsup'],
  },
  architectureType: 'monorepo',
  ownerStyle: 'pragmatic, ship fast, test critical paths',
  ownerPreferences: [
    'Zod schemas before implementation',
    'Collocate tests with source',
    'No barrel exports',
  ],
});

Add Constraints and Patterns

// Add a constraint
await dna.addConstraint({
  type: 'memory',
  rule: 'Node heap must stay under 7GB',
  severity: 'must',
  reason: 'Dev machine has 16GB RAM; uncapped builds crash the IDE',
});

// Record a learned pattern
await dna.addPattern({
  domain: 'api',
  pattern: 'All responses use successResponse() envelope: { data, meta }',
  confidence: 1.0,
  learnedFrom: ['apps/web/src/lib/api-response.ts'],
});

// Flag a risk zone
await dna.addRisk({
  path: 'packages/types/src/api',
  reason: 'Schema changes break both server and client if not updated in sync',
  breakFrequency: 0.3,
  lastBroken: Date.now(),
  mitigations: ['Update schema, server, and client together'],
});

Timeline -- Append-Only Reasoning Ledger

timeline.crtx is an ordered log of every decision, discovery, experiment, and failure across all agents. This is what prevents 10,000 agents from repeating the same mistakes.

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

const io = new CortexIO('/path/to/project');
const timeline = new Timeline(io);

await timeline.record({
  agentId: 'agent-42',
  type: 'decision',
  action: 'Chose Prisma over Drizzle for ORM',
  reasoning: 'Project already uses Prisma in 12 models; migration cost too high',
  context: {
    files: ['prisma/schema.prisma'],
    state: { existingModels: 12 },
  },
});

await timeline.record({
  agentId: 'agent-17',
  type: 'failure',
  action: 'Attempted to run tsc --noEmit on apps/web',
  reasoning: 'Full type-check OOMs on 16GB machine',
  context: {
    files: ['apps/web/tsconfig.json'],
    state: { heapUsed: '14GB' },
  },
});

Entry Types

Type	Purpose
`decision`	A choice was made between alternatives
`discovery`	New information about the codebase
`fix`	A bug was fixed
`refactor`	Code was restructured
`experiment`	Something was tried
`failure`	Something did not work
`learning`	A pattern was identified
`delegation`	Work was delegated to another agent
`escalation`	Issue was escalated to a human
`merge`	Agent outputs were merged
`conflict`	A merge conflict was detected

SemanticGraph -- Code Relationships

graph.crtx maps how your code is actually connected -- not just imports, but functional relationships like "tests", "implements", "configures", and "breaks if changed".

interface SemanticGraph {
  nodes: SemanticNode[];
  edges: SemanticEdge[];
  clusters: SemanticCluster[];
}

Nodes represent files, functions, types, modules, features, APIs, or tests. Edges describe relationships:

interface SemanticEdge {
  from: string;
  to: string;
  type: 'depends' | 'tests' | 'implements' | 'extends' | 'configures' | 'breaks_if_changed';
  weight: number;
  description: string;
}

Clusters group related nodes and measure cohesion (internal connectivity) and coupling (external dependencies).

SwarmManifest -- Multi-Agent Coordination

swarm.crtx defines the active swarm: which agents are working, what tasks are assigned, file locks, budget spent, and merge policy. See the Swarm Execution guide for details.

Using CortexIO to Read and Write

CortexIO is the low-level reader/writer for all .crtx files:

import { CortexIO } from '@codmir/cortex';

const io = new CortexIO('/path/to/project');

// Check if .cortex/ exists
const exists = await io.exists();

// Initialize the directory structure
await io.init();

// Read files
const dnaFile = await io.readDNA();         // CortexFile<ProjectDNA> | null
const timeline = await io.readTimeline();   // CortexFile<TimelineEntry[]> | null
const graph = await io.readGraph();         // CortexFile<SemanticGraph> | null
const swarm = await io.readSwarm();         // CortexFile<SwarmManifest> | null

// Write files (automatically sets header with checksum)
await io.writeDNA(projectDna);
await io.writeTimeline(entries);
await io.writeGraph(semanticGraph);
await io.writeSwarm(swarmManifest);

Next Steps

Swarm Execution -- use the protocol to coordinate thousands of agents
Self-Healing -- agents use the timeline to avoid repeating failed fixes
Smart Model Routing -- route different parts of the task to different models