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 tracesHow 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