Encode your project's intelligence — stack, architecture, constraints, patterns, and risks.

DNAManager

The DNAManager provides a high-level API for creating and managing ProjectDNA -- the structured encoding of your project's stack, architecture, constraints, learned patterns, and risk zones. It persists to manifest.crtx via CortexIO.

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

Constructor

new DNAManager(io: CortexIO)
ParameterTypeDescription
ioCortexIOThe CortexIO instance for file operations
const io = new CortexIO('/home/dev/my-project');
await io.init();
const dna = new DNAManager(io);

Methods

initialize()

Creates a new ProjectDNA from scratch and writes it to manifest.crtx.

async initialize(opts: {
  id: string;
  name: string;
  purpose: string;
  stack: Partial<StackFingerprint>;
  architectureType?: ArchitectureMap['type'];
  ownerStyle?: string;
  ownerPreferences?: string[];
}): Promise<ProjectDNA>
ParameterTypeDescription
opts.idstringProject identifier
opts.namestringHuman-readable project name
opts.purposestringOne-line description of the project
opts.stackPartial<StackFingerprint>Technology stack (languages, frameworks, etc.)
opts.architectureTypestring (optional)One of 'monorepo', 'polyrepo', 'monolith', 'microservices'. Default: 'monorepo'
opts.ownerStylestring (optional)Owner's coding style description
opts.ownerPreferencesstring[] (optional)Owner's technology preferences
const projectDna = await dna.initialize({
  id: 'codmir',
  name: 'Codmir',
  purpose: 'AI-powered project management and development platform',
  stack: {
    languages: ['TypeScript'],
    frameworks: ['Next.js', 'NestJS', 'React', 'Tauri'],
    databases: ['PostgreSQL', 'Redis'],
    infrastructure: ['Vercel', 'Railway', 'Cloudflare'],
    aiProviders: ['Anthropic', 'OpenAI', 'Google'],
    buildTools: ['turbo', 'tsup', 'pnpm'],
  },
  architectureType: 'monorepo',
  ownerStyle: 'type-first, pragmatic',
  ownerPreferences: ['TypeScript', 'Tailwind', 'Zod'],
});

get()

Returns the current ProjectDNA, or null if not initialized.

async get(): Promise<ProjectDNA | null>

addConstraint()

Adds a constraint to the project DNA.

async addConstraint(constraint: ProjectConstraint): Promise<void>
await dna.addConstraint({
  type: 'memory',
  rule: 'Node heap must not exceed 7GB',
  severity: 'must',
  reason: 'System has 16GB RAM; uncapped builds crash the IDE',
});

await dna.addConstraint({
  type: 'convention',
  rule: 'All API responses wrapped in { data, meta } envelope',
  severity: 'must',
  reason: 'Desktop client unwraps automatically via successResponse()',
});

addPattern()

Adds or updates a learned pattern. If a pattern with the same domain and pattern already exists, it is updated in place. The id and lastValidated fields are set automatically.

async addPattern(pattern: Omit<LearnedPattern, 'id' | 'lastValidated'>): Promise<void>
ParameterTypeDescription
pattern.domainstringPattern category (e.g., 'auth', 'api', 'build')
pattern.patternstringDescription of the pattern
pattern.confidencenumberConfidence score 0-1
pattern.learnedFromstring[]Source references (files, commits, etc.)
await dna.addPattern({
  domain: 'auth',
  pattern: 'CLI tokens are opaque 32-char strings, not JWTs',
  confidence: 1.0,
  learnedFrom: ['apps/web/src/lib/auth.ts', 'CLAUDE.md'],
});

addRisk()

Adds or updates a risk zone. If a risk with the same path exists, it is replaced.

async addRisk(risk: RiskZone): Promise<void>
await dna.addRisk({
  path: 'packages/types/src/api',
  reason: 'Shared types between server and client; mismatches cause runtime errors',
  breakFrequency: 5,
  lastBroken: Date.now(),
  mitigations: ['Zod schema validation on both sides', 'Integration tests'],
});

updateArchitecture()

Partially updates the architecture map.

async updateArchitecture(update: Partial<ArchitectureMap>): Promise<void>
await dna.updateArchitecture({
  entryPoints: ['apps/web/src/app/layout.tsx', 'apps/server/src/main.ts'],
  dataFlow: [
    {
      from: 'apps/desktop',
      to: 'apps/web',
      protocol: 'REST',
      description: 'Auth, CRUD operations',
    },
    {
      from: 'apps/desktop',
      to: 'apps/server',
      protocol: 'WebSocket',
      description: 'Realtime events, voice, MCP',
    },
  ],
});

updateOwner()

Updates the owner style and/or preferences.

async updateOwner(style?: string, preferences?: string[]): Promise<void>

getConstraints()

Returns constraints, optionally filtered by type.

async getConstraints(type?: ProjectConstraint['type']): Promise<ProjectConstraint[]>
const securityConstraints = await dna.getConstraints('security');

getPatterns()

Returns learned patterns, optionally filtered by domain.

async getPatterns(domain?: string): Promise<LearnedPattern[]>
const authPatterns = await dna.getPatterns('auth');

getRisks()

Returns all risk zones.

async getRisks(): Promise<RiskZone[]>

briefing()

Returns a human-readable markdown summary of the project DNA. Useful for generating context for agents.

async briefing(): Promise<string>
const brief = await dna.briefing();
console.log(brief);
// # Codmir
// AI-powered project management and development platform
//
// ## Stack
// Languages: TypeScript
// Frameworks: Next.js, NestJS, React, Tauri
// AI Providers: Anthropic, OpenAI, Google
//
// ## Architecture: monorepo
// ...

Types

ProjectDNA

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[];
}

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[];
}