The AI-native file format — ProjectDNA, Timeline, SemanticGraph, and SwarmManifest.

Cortex Protocol

The Cortex Protocol is a structured file format for AI agent communication. Every project gets a .cortex/ directory where agents read and write structured reasoning, project intelligence, and coordination data. This is what lets thousands of agents work on the same codebase without repeating mistakes or stepping on each other.

Humans do not read these files directly. They are a language for AI agents.

Directory Structure

.cortex/
  manifest.crtx        # ProjectDNA — stack, architecture, constraints, patterns
  timeline.crtx         # TimelineEntry[] — append-only reasoning ledger
  graph.crtx            # SemanticGraph — how things actually connect
  swarm.crtx            # SwarmManifest — active multi-agent coordination
  reasoning/
    <taskId>.crtx       # TimelineEntry[] — per-task reasoning trace

Every .crtx file is a JSON file wrapped in a protocol envelope:

interface CortexFile<T> {
  header: CortexFileHeader;
  data: T;
}

interface CortexFileHeader {
  cortex: 1;
  type: 'dna' | 'timeline' | 'graph' | 'swarm' | 'reasoning';
  project: string;
  created: number;
  updated: number;
  checksum: string;
}

Classes

Use these classes to interact with the protocol:

Class	Description
CortexIO	Filesystem interface for reading and writing `.cortex/` files
DNAManager	Manage ProjectDNA — stack, architecture, constraints, patterns, risks
Timeline	Append-only reasoning ledger with buffering and auto-flush
SwarmProtocol	Multi-agent coordination with task decomposition, file locking, and budget tracking

ProjectDNA

The invisible knowledge that senior developers carry in their heads, encoded as structured data.

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[];
    timezone?: string;
  };
}

StackFingerprint

interface StackFingerprint {
  languages: string[];
  frameworks: string[];
  databases: string[];
  infrastructure: string[];
  aiProviders: string[];
  buildTools: string[];
}

ArchitectureMap

interface ArchitectureMap {
  type: 'monorepo' | 'polyrepo' | 'monolith' | 'microservices';
  entryPoints: string[];
  boundaries: ArchitectureBoundary[];
  dataFlow: DataFlowEdge[];
}

interface ArchitectureBoundary {
  name: string;
  paths: string[];
  owns: string[];
  exposesTo: string[];
}

interface DataFlowEdge {
  from: string;
  to: string;
  protocol: string;
  description: string;
}

ProjectConstraint

interface ProjectConstraint {
  type: 'memory' | 'cost' | 'latency' | 'security' | 'compliance' | 'convention';
  rule: string;
  severity: 'must' | 'should' | 'prefer';
  reason: string;
}

LearnedPattern

interface LearnedPattern {
  id: string;
  domain: string;
  pattern: string;
  confidence: number;
  learnedFrom: string[];
  lastValidated: number;
}

RiskZone

interface RiskZone {
  path: string;
  reason: string;
  breakFrequency: number;
  lastBroken: number;
  mitigations: string[];
}

Timeline Entries

Every decision, discovery, failure, and learning is recorded as a TimelineEntry.

interface TimelineEntry {
  id: string;
  timestamp: number;
  agentId: string;
  type: TimelineEntryType;
  action: string;
  reasoning: string;
  confidence: number;
  context: TimelineContext;
  refs: string[];
  outcome: 'success' | 'failure' | 'pending' | 'abandoned';
  outcomeDetail?: string;
  parent?: string;
  children?: string[];
}

TimelineEntryType

type TimelineEntryType =
  | 'decision'
  | 'discovery'
  | 'fix'
  | 'refactor'
  | 'experiment'
  | 'failure'
  | 'learning'
  | 'delegation'
  | 'escalation'
  | 'merge'
  | 'conflict';

Type	When to use
`decision`	Agent chose between alternatives
`discovery`	Agent found something unexpected
`fix`	Agent fixed a bug
`refactor`	Agent restructured code
`experiment`	Agent tried something that may or may not work
`failure`	Something went wrong
`learning`	Agent derived a reusable insight
`delegation`	Agent assigned work to another agent
`escalation`	Agent escalated to a human or coordinator
`merge`	Agent merged results from multiple agents
`conflict`	File or logic conflict between agents

TimelineContext

interface TimelineContext {
  files: string[];
  task?: string;
  branch?: string;
  trigger?: string;
  dependencies?: string[];
  state: Record<string, unknown>;
}

Swarm Types

SwarmManifest

interface SwarmManifest {
  id: string;
  task: string;
  created: number;
  coordinator: string;
  strategy: SwarmStrategy;
  agents: SwarmAgent[];
  locks: SwarmLock[];
  decomposition: TaskNode;
  mergePolicy: MergePolicy;
  budget: SwarmBudget;
}

SwarmStrategy

type SwarmStrategy =
  | 'parallel'       // all agents work independently, merge at end
  | 'pipeline'       // sequential, each agent's output feeds the next
  | 'hierarchical'   // queen delegates to workers
  | 'consensus'      // agents vote on approach before executing
  | 'competitive';   // multiple agents solve same task, best wins

SwarmAgent

interface SwarmAgent {
  id: string;
  role: string;
  expertise: string[];
  assignedTasks: string[];
  status: 'idle' | 'working' | 'blocked' | 'done' | 'failed';
  startedAt?: number;
  completedAt?: number;
  tokensUsed: number;
  costUsd: number;
}

TaskNode

interface TaskNode {
  id: string;
  description: string;
  assignedTo?: string;
  status: 'pending' | 'active' | 'done' | 'failed' | 'skipped';
  priority: number;
  estimatedTokens: number;
  actualTokens?: number;
  dependencies: string[];
  children: TaskNode[];
  output?: unknown;
}

SwarmBudget

interface SwarmBudget {
  maxAgents: number;
  maxTokens: number;
  maxCostUsd: number;
  maxDurationMs: number;
  spent: {
    agents: number;
    tokens: number;
    costUsd: number;
    durationMs: number;
  };
}

MergePolicy

interface MergePolicy {
  strategy: 'auto' | 'voting' | 'coordinator_review' | 'human_review';
  conflictResolution: 'last_write' | 'highest_confidence' | 'coordinator_decides' | 'vote';
  minAgreePercent?: number;
  requireHumanApproval: boolean;
}

SwarmLock

interface SwarmLock {
  path: string;
  agentId: string;
  type: 'exclusive' | 'shared';
  acquiredAt: number;
  expiresAt: number;
  reason: string;
}

Semantic Graph

How things actually connect -- not just imports, but semantic relationships.

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

interface SemanticNode {
  id: string;
  type: 'file' | 'function' | 'type' | 'module' | 'feature' | 'api' | 'test';
  path: string;
  name: string;
  importance: number;
  fragility: number;
  lastTouched: number;
  touchCount: number;
}

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

interface SemanticCluster {
  id: string;
  name: string;
  nodes: string[];
  cohesion: number;
  coupling: number;
}