Cortex Learning System

Cortex Learning System

The Learning System enables Cortex V2 to improve from corrections and feedback, creating a continuously improving knowledge base.

Overview

When you correct the AI, Cortex V2:

1. Analyzes the correction to understand what went wrong
2. Categorizes it into one of 10 correction types
3. Extracts generalizable principles
4. Creates new memories from the learning
5. Calibrates confidence based on evidence

Correction Categories

Category	Description	Example
security	Security-related corrections	"Don't use MD5, use bcrypt"
performance	Performance improvements	"Use pagination for large lists"
style	Code style preferences	"Use early returns"
architecture	Structural decisions	"Services shouldn't call controllers"
naming	Naming conventions	"Use camelCase for functions"
error_handling	Error handling patterns	"Always wrap async in try-catch"
testing	Testing practices	"Mock external services"
documentation	Documentation standards	"Add JSDoc to public functions"
api_design	API design patterns	"Use REST conventions"
data_handling	Data management	"Validate input at boundaries"

Learning Flow

┌─────────────────┐
│   Correction    │
│   "Use bcrypt"  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│    Analyzer     │
│  - Diff code    │
│  - Extract why  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   Categorizer   │
│  → "security"   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   Principle     │
│   Extractor     │
│  → "Use secure  │
│    hashing"     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Memory Factory  │
│  - Tribal       │
│  - Pattern      │
│  - Smell        │
└─────────────────┘

API Usage

Learn from Correction

await cortex.learn(
  'Use MD5 for hashing',           // Original (wrong)
  'MD5 is insecure. Use bcrypt.',  // Correction
  'const hash = await bcrypt.hash(password, 10);',  // Correct code
  {
    activeFile: 'src/auth.ts',
    intent: 'fix_bug',
    severity: 'high'
  }
);

Provide Feedback

// Confirm a memory is correct
await cortex.feedback('mem_abc123', 'confirmed');

// Reject a memory
await cortex.feedback('mem_abc123', 'rejected', {
  reason: 'This pattern is outdated'
});

// Modify a memory
await cortex.feedback('mem_abc123', 'modified', {
  newContent: 'Updated guidance...'
});

Confidence Calibration

Confidence is calculated from multiple signals:

interface ConfidenceMetrics {
  usageCount: number;      // Times memory was used
  confirmations: number;   // Positive feedback
  rejections: number;      // Negative feedback
  age: number;             // Days since creation
  sourceReliability: number; // Trust in source
}

function calculateConfidence(metrics: ConfidenceMetrics): number {
  const usageScore = Math.min(metrics.usageCount / 10, 1) * 0.3;
  const feedbackScore = (metrics.confirmations - metrics.rejections) / 
    (metrics.confirmations + metrics.rejections + 1) * 0.4;
  const ageDecay = Math.exp(-metrics.age / 365) * 0.1;
  const sourceScore = metrics.sourceReliability * 0.2;
  
  return Math.max(0, Math.min(1, usageScore + feedbackScore + ageDecay + sourceScore));
}

Active Learning

The system identifies memories that need validation:

Validation Candidates

interface ValidationCandidate {
  memoryId: string;
  reason: 'low_confidence' | 'conflicting' | 'stale' | 'unused';
  priority: number;
  suggestedPrompt: string;
}

Validation Prompts

const candidates = await cortex.getValidationCandidates(5);
// Returns memories that need human review

for (const candidate of candidates) {
  console.log(candidate.suggestedPrompt);
  // "Is this still accurate? 'Always use bcrypt for passwords'"
}

Memory Creation from Learning

Tribal Knowledge

Created when learning reveals team conventions:

{
  type: 'tribal_knowledge',
  content: 'Always use bcrypt for password hashing',
  source: 'correction',
  confidence: 0.8,
  category: 'security'
}

Pattern Rationale

Created when learning explains why a pattern exists:

{
  type: 'pattern_rationale',
  content: 'JWT tokens are used because the API is stateless',
  patternId: 'jwt-auth-pattern',
  source: 'correction',
  confidence: 0.75
}

Code Smell

Created when learning identifies anti-patterns:

{
  type: 'code_smell',
  content: 'Using MD5 for password hashing is insecure',
  severity: 'high',
  source: 'correction',
  confidence: 0.9
}

MCP Tools

drift_memory_learn

Learn from a correction:

{
  "original": "Use MD5 for hashing",
  "correction": "MD5 is insecure. Use bcrypt.",
  "correctCode": "const hash = await bcrypt.hash(password, 10);",
  "context": {
    "file": "src/auth.ts",
    "intent": "fix_bug"
  }
}

drift_memory_feedback

Provide feedback on a memory:

{
  "memoryId": "mem_abc123",
  "action": "confirmed"
}

drift_memory_validate

Get memories needing validation:

{
  "limit": 5,
  "includePrompts": true
}

Metrics & Health

Track learning system health:

const health = await cortex.getLearningHealth();
// {
//   totalCorrections: 47,
//   categorizedCorrections: 45,
//   principlesExtracted: 32,
//   memoriesCreated: 28,
//   averageConfidence: 0.78,
//   validationBacklog: 5
// }

Best Practices

1. Provide context — Include file and intent when learning
2. Be specific — Explain WHY something is wrong
3. Include correct code — Show the right way
4. Review candidates — Regularly validate low-confidence memories
5. Track metrics — Monitor learning health

Related Documentation

• Cortex V2 Overview
• Causal Graphs
• Token Efficiency
• MCP Tools Reference