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 traceEvery .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 winsSwarmAgent
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;
}