ruvnet__ruflo/v3/plugins/cognitive-kernel/README.md

@claude-flow/plugin-cognitive-kernel

A cutting-edge cognitive augmentation plugin combining the Cognitum Gate Kernel with SONA self-optimizing architecture to provide LLMs with enhanced cognitive capabilities. The plugin enables dynamic working memory, attention control mechanisms, meta-cognitive self-monitoring, and cognitive scaffolding while maintaining low latency through WASM acceleration.

Installation

npm

npm install @claude-flow/plugin-cognitive-kernel

CLI

npx claude-flow plugins install --name @claude-flow/plugin-cognitive-kernel

Quick Start

import { CognitiveKernelPlugin } from '@claude-flow/plugin-cognitive-kernel';

// Initialize the plugin
const plugin = new CognitiveKernelPlugin();
await plugin.initialize();

// Allocate working memory for a complex reasoning task
const memorySlot = await plugin.workingMemory({
  action: 'allocate',
  slot: {
    id: 'current-problem',
    content: { problem: 'Design authentication system', context: {...} },
    priority: 0.9,
    decay: 0.05
  },
  capacity: 7  // Miller's number
});

// Control attention for focused analysis
await plugin.attentionControl({
  mode: 'focus',
  targets: [
    { entity: 'security-requirements', weight: 0.8, duration: 300 },
    { entity: 'user-experience', weight: 0.6, duration: 300 }
  ],
  filters: {
    includePatterns: ['auth*', 'security*', 'token*'],
    noveltyBias: 0.3
  }
});

console.log('Cognitive context established');

Available MCP Tools

1. cognition/working-memory

Manage dynamic working memory slots for complex reasoning tasks.

const result = await mcp.call('cognition/working-memory', {
  action: 'allocate',
  slot: {
    id: 'task-context',
    content: {
      goal: 'Refactor authentication module',
      constraints: ['maintain backward compatibility', 'improve security'],
      progress: []
    },
    priority: 0.8,
    decay: 0.1
  },
  capacity: 7,
  consolidationTarget: 'episodic'
});

Actions: allocate, update, retrieve, clear, consolidate

Returns: Memory slot state with current contents and decay status.

2. cognition/attention-control

Control cognitive attention and information filtering.

const result = await mcp.call('cognition/attention-control', {
  mode: 'selective',
  targets: [
    { entity: 'error-handling', weight: 0.9, duration: 600 },
    { entity: 'input-validation', weight: 0.7, duration: 600 }
  ],
  filters: {
    includePatterns: ['error*', 'exception*', 'validation*'],
    excludePatterns: ['deprecated*', 'legacy*'],
    noveltyBias: 0.5
  }
});

Modes: focus, diffuse, selective, divided, sustained

Returns: Attention state with active targets and filter configuration.

3. cognition/meta-monitor

Meta-cognitive monitoring of reasoning quality and self-reflection.

const result = await mcp.call('cognition/meta-monitor', {
  monitoring: [
    'confidence_calibration',
    'reasoning_coherence',
    'goal_tracking',
    'error_detection'
  ],
  reflection: {
    trigger: 'on_uncertainty',
    depth: 'medium'
  },
  interventions: true
});

Returns: Meta-cognitive assessment with confidence scores, detected issues, and suggested interventions.

4. cognition/scaffold

Provide cognitive scaffolding for complex reasoning tasks.

const result = await mcp.call('cognition/scaffold', {
  task: {
    description: 'Design a distributed caching system',
    complexity: 'complex',
    domain: 'distributed-systems'
  },
  scaffoldType: 'decomposition',
  adaptivity: {
    fading: true,
    monitoring: true
  }
});

Scaffold Types: decomposition, analogy, worked_example, socratic, metacognitive_prompting, chain_of_thought

Returns: Structured scaffolding with step-by-step guidance adapted to task complexity.

5. cognition/cognitive-load

Monitor and balance cognitive load during reasoning.

const result = await mcp.call('cognition/cognitive-load', {
  assessment: {
    intrinsic: 0.7,    // Task complexity
    extraneous: 0.3,   // Presentation complexity
    germane: 0.5       // Learning investment
  },
  optimization: 'reduce_extraneous',
  threshold: 0.8
});

Optimizations: reduce_extraneous, chunk_intrinsic, maximize_germane, balanced

Returns: Load assessment with optimization recommendations and intervention triggers.

Configuration Options

interface CognitiveKernelConfig {
  // Maximum working memory slots (default: 7, Miller's number)
  maxWorkingMemorySlots: number;

  // Memory limit in MB (default: 256)
  memoryLimit: number;

  // CPU time limit per operation in seconds (default: 10)
  cpuTimeLimit: number;

  // Enable session isolation (default: true)
  sessionIsolation: boolean;

  // Scaffold fading configuration
  scaffolding: {
    enableFading: boolean;
    fadingRate: number;
  };

  // Meta-cognitive intervention thresholds
  metaCognition: {
    confidenceThreshold: number;
    coherenceThreshold: number;
    autoIntervene: boolean;
  };
}

Performance Targets

Metric	Target	Notes
Working memory operations	<1ms per slot	10x faster than naive cache
Attention steering	<5ms for reallocation	10x faster than context rebuild
Meta-cognitive check	<10ms per assessment	Novel capability
Memory consolidation	<100ms batch	10x faster than full reindex
Scaffold generation	<50ms per step	Novel capability

Cognitive Theories Implemented

Theory	Implementation
Baddeley's Working Memory	Multi-component memory system with phonological loop, visuospatial sketchpad, and episodic buffer
Cognitive Load Theory	Intrinsic/extraneous/germane load management
Metacognition	Self-monitoring, error detection, and regulation
Zone of Proximal Development	Adaptive scaffolding with gradual fading
Dual Process Theory	Fast/slow thinking modes

Security Considerations

• Session Isolation: Each cognitive session has isolated working memory with session-specific encryption keys (AES-256-GCM)
• Secure Clearing: Working memory is securely cleared and overwritten (zero-fill) at session end
• Prompt Injection Prevention: Scaffold content is sanitized to remove potential prompt injection patterns (special tokens, control sequences)
• Input Validation: All inputs validated with Zod schemas with strict limits
• Rate Limiting: Prevents abuse of cognitive resources
• Content Filtering: Memory content scanned for sensitive data patterns before storage

WASM Security Constraints

Constraint	Value	Rationale
Memory Limit	256MB	Sufficient for cognitive operations
CPU Time per Operation	10 seconds	Prevent runaway processing
No Network Access	Enforced	Prevent data exfiltration
Session Isolation	Enforced	Per-session WASM instances
Secure Memory Clear	Zero-fill on exit	Prevent memory forensics

Input Limits

Constraint	Limit
Working memory slots	20 max
Memory limit	256MB
CPU time per operation	10 seconds
Attention targets	50 max
Scaffold description	5,000 characters

Rate Limits

Tool	Requests/Minute	Max Concurrent
working-memory	120	10
attention-control	60	5
meta-monitor	60	5
scaffold	30	3
cognitive-load	60	5

Dependencies

• cognitum-gate-kernel - Core cognitive kernel for memory gating and attention control
• sona - Self-Optimizing Neural Architecture for adaptive cognition
• ruvector-attention-wasm - Multi-head attention for cognitive focus
• ruvector-nervous-system-wasm - Coordination between cognitive subsystems
• micro-hnsw-wasm - Fast retrieval for episodic memory

Use Cases

1. Complex Reasoning: Support multi-step reasoning with working memory persistence
2. Research Synthesis: Maintain focus across long document analysis sessions
3. Learning Enhancement: Adaptive scaffolding for skill acquisition
4. Error Prevention: Meta-cognitive monitoring catches reasoning errors before output
5. Context Management: Intelligent attention control for managing long contexts

Related Plugins

Plugin	Description	Synergy
@claude-flow/plugin-neural-coordination	Multi-agent coordination	Cognitive kernel provides enhanced reasoning for coordinated agents
@claude-flow/plugin-hyperbolic-reasoning	Hierarchical reasoning	Combines hierarchical structure with cognitive scaffolding
@claude-flow/plugin-quantum-optimizer	Quantum-inspired optimization	Optimizes cognitive resource allocation and attention scheduling

Architecture

+------------------+     +----------------------+     +------------------+
|    LLM Input     |---->|  Cognitive Kernel    |---->|  Enhanced Output |
|   (Prompts)      |     |  (WASM Accelerated)  |     |  (Augmented)     |
+------------------+     +----------------------+     +------------------+
                                   |
              +--------------------+--------------------+
              |                    |                    |
       +------+------+     +-------+-------+    +------+------+
       | Cognitum    |     |    SONA       |    | Attention   |
       | Gate Kernel |     | Self-Optimize |    | Control     |
       +-------------+     +---------------+    +-------------+
              |                    |                    |
              +--------------------+--------------------+
                                   |
                           +-------+-------+
                           | Working Memory |
                           | (HNSW Index)   |
                           +---------------+

License

MIT