agent-shadow-brain

The World's #1 Hyper-Cognitive AI Coding Brain

Shadow Brain is a zero-config, self-evolving, infinite-memory intelligence layer that makes every AI coding agent write better, safer, faster code. Install it once, and it automatically detects your project, your AI tools, your frameworks — and starts making your agents smarter forever.

v5.1.1 — Hyper-Cognitive Intelligence Edition: 6 new brain modules — Built-in LSP Server for real-time IDE feedback, Custom LLM Fine-Tuning Engine to train on your codebase, Smart Cache with multi-tier predictive prefetch, Intent Engine for natural language command understanding, Code DNA fingerprinting with 9-gene analysis, and Temporal Intelligence for velocity tracking & bug prediction. Plus all v5.0.1 zero-config features (MCP server, dashboard, plugins, export/import), v5.0.0 infinite intelligence (hierarchical memory, consensus, collective learning), and v4.0.0 hyper-intelligence (TurboQuant, SSSP, self-evolution, adversarial defense, swarm, knowledge graph, predictive engine).

Install Now · Dashboard · v5.1.1 New · Algorithms · CLI Reference · Architecture

The Problem

You use AI coding agents. They're powerful, but:

The Solution

Shadow Brain v5.1.1 — zero-config, auto-detecting, infinite-intelligence shadow layer:

┌──────────────┐    auto-detect     ┌──────────────────────────────────────────┐
│  AI Agents   │ ◀────────────────  │         SHADOW BRAIN v5.1.1              │
│ Claude Code  │  MCP auto-install  │                                          │
│ Cursor       │  zero-config       │  ┌─ HYPER-COGNITIVE (v5.1.1 NEW) ────┐  │
│ Kilo Code    │                    │  │ Built-in LSP Server (stdio+TCP)   │  │
│ Cline        │    watches         │  │ Custom LLM Fine-Tuning Engine     │  │
│ OpenCode     │ ──────────────▶   │  │ Smart Cache (hot/warm/cold tiers) │  │
│ Codex        │  file changes      │  │ Intent Engine (NLP commands)      │  │
│ Roo Code     │  git commits       │  │ Code DNA (9-gene fingerprinting) │  │
│ Aider        │  activity          │  │ Temporal Intelligence (velocity)  │  │
│ Windsurf     │                    │  └────────────────────────────────────┘  │
└──────────────┘                    │  ┌─ ZERO-CONFIG (v5.0.1) ─────────────┐  │
         ▲                          │  │ Auto-detect + MCP + Dashboard      │  │
         │                          │  │ Plugins + Export/Import + Hooks    │  │
         │                          │  └────────────────────────────────────┘  │
         │                          │  ┌─ INFINITE MEMORY (v5.0.0) ────────┐  │
         │                          │  │ 4-tier hierarchical compression    │  │
         │                          │  │ Context-triggered recall            │  │
         │                          │  │ Multi-agent consensus + trust       │  │
         │                          │  │ Collective cross-project learning   │  │
         │                          │  └────────────────────────────────────┘  │
         │                          │  ┌─ HYPER-INTELLIGENCE (v4) ──────────┐  │
         │                          │  │ TurboQuant 6x Compression           │  │
         │                          │  │ SSSP BMSSP Quantum Routing          │  │
         │                          │  │ Self-Evolution + CAIP + Swarm       │  │
         │                          │  │ PageRank + Predictive + Adversarial │  │
         └──────────────────────────┴──────────────────────────────────────────┘

v5.1.1 — What's New

6 Hyper-Cognitive Brain Modules

shadow-brain lsp --stdio          # stdio mode (for editors)
shadow-brain lsp --tcp 2087       # TCP mode (for remote)

shadow-brain fine-tune status             # Training data stats
shadow-brain fine-tune generate [dir]     # Generate training pairs
shadow-brain fine-tune export [path]      # Export JSONL dataset

shadow-brain cache stats          # Hit rate, tier sizes, memory usage
shadow-brain cache clear          # Clear all tiers

shadow-brain intent "find security bugs"    # Maps to: analyze + security filter
shadow-brain intent "show hot files"        # Maps to: temporal + heatmap

shadow-brain dna analyze [dir]    # Generate DNA profiles
shadow-brain dna compare f1 f2    # Compare two file fingerprints
shadow-brain dna similar [file]   # Find similar files

shadow-brain temporal stats       # Velocity, anomalies, predictions
shadow-brain temporal hot         # Top 10 hottest files
shadow-brain temporal predict     # Bug risk predictions
shadow-brain temporal timeline    # Recent event timeline

v5.0.1 — What's New

Zero-Config Auto-Setup

Install it. That's it. Shadow Brain automatically:

• Detects your project type (frontend, backend, fullstack, mobile, game, systems, data-science)
• Detects 25+ languages, 15+ frameworks, 5+ build tools, 5+ test frameworks
• Detects which AI tools are installed (Claude Code, Cursor, Kilo Code, Cline, OpenCode, Codex, Aider, Windsurf)
• Auto-installs MCP server configuration for every detected AI tool
• Auto-installs git pre-commit and pre-push hooks
• Generates an optimal brain config based on project complexity

npm install @theihtisham/agent-shadow-brain
# → Shadow Brain v5.1.1 auto-configured for my-app (fullstack)
# → AI tools detected: Claude Code, Cursor
# → Run: shadow-brain start

MCP Server — Works with EVERY AI Tool

The brain exposes itself as a Model Context Protocol (MCP) server with 19 tools that any AI tool can call:

Works with Claude Code, Cursor, Kilo Code, Cline, OpenCode, and any MCP-compatible AI tool.

# Start MCP server (auto-started by AI tools)
shadow-brain mcp

# Cursor compatibility (root path POST + /v1/chat)
# Claude Code compatibility (JSON-RPC 2.0 over stdio/HTTP)

Rich Web Dashboard

Real-time browser dashboard at http://localhost:7341 with WebSocket live updates:

• Stats Topbar: 8 live counters — Insights, Fixes, Memory KB, Modules, AI Tools, Evolution Gen, Swarm Convergence, Turbo Compression
• Health Score: A-F grading with dimension breakdown (Security, Quality, Performance, Architecture, Maintainability, Test Coverage)
• Memory Tiers: Visual bars showing Raw (50K), Summary (10K), Pattern (2K), Principle (500) with Turbo compression ratio
• Live Insights Stream: Real-time feed of brain insights with priority badges
• Smart Fixes: Actionable fix suggestions with file/line references
• AI Tools Panel: 8 tools showing connected/detected status
• Brain Modules: 13 modules with active/idle/error indicators
• Control Buttons: Trigger analysis on-demand, refresh data

shadow-brain start .     # Dashboard auto-starts at http://localhost:7341
shadow-brain dash .      # Dashboard only mode

Natural Language Queries

Ask your brain questions in plain English:

shadow-brain ask "What security issues exist in the auth module?"
shadow-brain ask "Which files have the highest bug risk?"
shadow-brain ask "What patterns have we learned about React hooks?"

Brain Export/Import — Team Sync

Export your brain state and share it with your team:

shadow-brain export                    # Full export with all modules
shadow-brain export -o ./team-brain    # Custom output directory
shadow-brain import brain-export.json  # Import + merge
shadow-brain import brain-export.json --merge --skip swarm,evolution

Plugin System

Extend Shadow Brain with custom plugins:

shadow-brain plugin list               # List installed plugins
shadow-brain plugin create my-plugin   # Create from template
shadow-brain plugin stats              # Plugin system statistics

Plugins can hook into pre-analysis and post-analysis pipelines to add custom insights, filter results, or integrate with external services.

5 New Commands

shadow-brain off          # Clean shutdown
shadow-brain ask "..."    # Natural language query
shadow-brain export       # Export brain state
shadow-brain import FILE  # Import brain state
shadow-brain plugin CMD   # Plugin management

Getting Started — 30 Seconds

# Install globally
npm install -g @theihtisham/agent-shadow-brain

# Or use npx (no install needed)
npx @theihtisham/agent-shadow-brain start .

That's literally it. Shadow Brain will:

1. Auto-detect your project, languages, frameworks, AI tools (zero config)
2. Auto-install MCP server config for Claude Code, Cursor, Kilo Code, Cline, etc.
3. Auto-install git hooks for pre-commit and pre-push
4. Watch your project files for changes
5. Analyze every change with LLM + 22 brain modules
6. Inject expert insights into your agent's memory
7. Store all knowledge in hierarchical memory for infinite retention
8. Activate past memories automatically based on context
9. Share verified patterns across projects via collective learning
10. Compress knowledge with TurboQuant for infinite retention
11. Evolve its own rules via genetic algorithm
12. Share insights across agents via CAIP
13. Detect hallucinations with adversarial verification
14. Run consensus when multiple agents disagree
15. Serve a rich web dashboard at localhost:7341

Quick Review (No Watch Mode)

shadow-brain review .                    # One-shot analysis
shadow-brain review . --show-health      # + health score
shadow-brain review . --show-fixes       # + fix suggestions
shadow-brain review . --output json      # JSON for scripting

Web Dashboard

The v5.1.1 dashboard provides a real-time view into your brain:

┌──────────────────────────────────────────────────────────────────────────┐
│  Shadow Brain v5.1.1                                     [Analyze] [↻] │
├──────────────────────────────────────────────────────────────────────────┤
│  Insights: 142 │ Fixes: 38 │ Memory: 247KB │ Modules: 22/22 │ ...     │
├──────────────┬─────────────────────────────────────┬───────────────────┤
│ Health: 87%  │  Live Insights Stream               │ AI Tools          │
│ ████████░░   │  ● [HIGH] SQL injection in login.ts │ ● Claude Code ✓  │
│ Security: A  │  ● [MED] Missing error handling     │ ● Cursor    ✓    │
│ Quality: B+  │  ● [LOW] Unused import in utils     │ ● Kilo Code ✓    │
│ Perf:    A-  │  ● [CRIT] Exposed API key           │ ● Cline     —    │
│ Arch:    B   │                                     │ ● OpenCode  —    │
│ Maintain: A  ├─────────────────────────────────────┤ ● Codex     —    │
│ Tests:   C+  │  Smart Fixes                        │ ● Aider     —    │
│              │  1. Add parameterized query...       │ ● Windsurf  —    │
├──────────────┤  2. Wrap in try/catch with...       ├───────────────────┤
│ Memory Tiers │  3. Remove unused import on L42     │ Brain Modules     │
│ Raw:   8421  │                                     │ ● Hierarchical ✓  │
│ Summ:  1203  │                                     │ ● TurboMemory  ✓  │
│ Patt:   187  │                                     │ ● Consensus    ✓  │
│ Princ:    24 │                                     │ ● Swarm        ✓  │
│ Turbo: 6.2x  │                                     │ ● Evolution    ✓  │
│              │                                     │ ● Adversarial  ✓  │
└──────────────┴─────────────────────────────────────┴───────────────────┘

v5.0.0 Infinite Intelligence Engine

4 Breakthrough Modules

shadow-brain memory stats          # 4 tiers | 12,847 entries
shadow-brain memory store "..."    # Store new knowledge
shadow-brain memory search "auth"  # Cross-tier semantic search

shadow-brain recall . --file src/auth/login.ts --keywords "jwt,session"
# → Activates 8 memories | Top: "JWT rotation pattern (92%)"

shadow-brain consensus status
shadow-brain consensus propose "Use bcrypt for all password hashing" security 0.95
shadow-brain consensus vote <id> agree 0.9 "Industry standard"
shadow-brain consensus results

shadow-brain collective status
shadow-brain collective propose "Always validate file upload MIME types" security
shadow-brain collective search performance

v4.0.0 Hyper-Intelligence Engine

8 Breakthrough Modules (included in v5.1.1)

shadow-brain turbo stats
shadow-brain turbo search "authentication patterns"

shadow-brain route status
shadow-brain route find node-A node-B

shadow-brain evolve status
shadow-brain evolve run
shadow-brain evolve best-rules security

shadow-brain caip status
shadow-brain caip broadcast "Security pattern detected"

shadow-brain defense status
shadow-brain defense scan "This API endpoint exists at /api/v2/users"

shadow-brain swarm status
shadow-brain swarm priorities

shadow-brain graph build .
shadow-brain graph pagerank
shadow-brain graph cycles

shadow-brain predict bugs .

Algorithms & Research

Shadow Brain v5.1.1 implements algorithms from peer-reviewed research:

TurboQuant Pipeline Detail

Input Vector (64-dim, float64)
     |
     v
+-------------+
|  PolarQuant  |-- Cartesian -> Polar coordinates
|  2 bits/dim  |-- Quantize angles to 4 levels (2 bits each)
+------+-------+   Pack into Uint8Array
       |
       v
+-------------+
|  QJL Residual|-- Random rotation (Hadamard-like)
|  1 bit/dim   |-- Sign extraction (1 bit per dim)
+------+-------+   Pack into Uint8Array
       |
       v
  TurboVector { polar: Uint8Array, qjl: Uint8Array, dim: number, radius: number }
  = 3 bits/dim total = 6x compression from float64
  = ZERO FORGETTING -- compressed knowledge stays searchable forever

Features

Architecture

v5.1.1 Module Map (22 modules)

CLI Reference

Core Commands

v5.1.1 Hyper-Cognitive Commands (NEW)

v5.0.1 Commands

v5.0.0 Infinite Intelligence Commands

v4.0.0 Hyper-Intelligence Commands

Programmatic API

import {
  Orchestrator,
  // v5.1.1 — Hyper-Cognitive modules
  LSPServer,
  FineTuningEngine,
  SmartCache,
  IntentEngine,
  CodeDNA,
  TemporalIntelligence,
  // v5.0.1 — Zero-Config modules
  AutoSetup,
  PluginSystem,
  BrainPortability,
  // v5.0.0 — Infinite Intelligence modules
  HierarchicalMemory,
  ContextRecall,
  ConsensusEngine,
  CollectiveLearning,
  // v4.0.0 — Hyper-Intelligence modules
  TurboMemory,
  SSSPRouter,
  SelfEvolution,
  CrossAgentProtocol,
  AdversarialDefense,
  SwarmIntelligence,
  KnowledgeGraph,
  PredictiveEngine,
  NeuralMesh,
} from '@theihtisham/agent-shadow-brain';

// v5.1.1 — Built-in LSP server
const lsp = new LSPServer('./my-project');
lsp.start({ mode: 'tcp', port: 2087 }); // or { mode: 'stdio' }

// v5.1.1 — Smart Cache
const cache = new SmartCache({ maxHotEntries: 200, enablePrefetch: true });
cache.set('analysis:auth', analysisResult, { ttl: 300_000, tags: ['security'] });
const cached = cache.get('analysis:auth');

// v5.1.1 — Temporal Intelligence
const temporal = new TemporalIntelligence('./my-project');
temporal.recordCommit(['src/auth.ts'], 'fix: JWT rotation');
const velocity = temporal.getVelocity(); // { daily, weekly, trend: 'accelerating' }
const bugRisks = temporal.predictBugs(10);

// v5.1.1 — Code DNA
const dna = new CodeDNA('./my-project');
const profile = await dna.analyze('src/auth.ts');
const similar = await dna.findSimilar('src/auth.ts', 5);

// v5.0.1 — Zero-config auto-setup
const setup = new AutoSetup('./my-project');
const config = await setup.detect();
// → { projectType: 'fullstack', languages: ['typescript','python'], frameworks: ['next.js'], aiTools: [...] }
await setup.installMCPForTools(['Claude Code', 'Cursor']);
await setup.installGitHooks();

// Create the brain
const brain = new Orchestrator({
  provider: 'anthropic',
  projectDir: './my-project',
  agents: ['claude-code', 'cursor', 'cline'],
  watchMode: true,
  autoInject: true,
  brainPersonality: 'balanced',
});

// v5.0.1 — Plugin system
const plugins = new PluginSystem('./my-project');
await plugins.loadAll();
await plugins.preAnalysis({ files: ['src/auth.ts'], projectDir: './my-project' });

// v5.0.1 — Brain portability
const porter = new BrainPortability('./my-project');
const { filePath, sizeBytes, checksum } = await porter.exportBrain();

// v5.0.0 — Infinite Intelligence
const hmem = new HierarchicalMemory();
await hmem.store('JWT rotation pattern: rotate every 24h with refresh tokens', 'security', 0.9);
const results = hmem.search('jwt');

const recall = new ContextRecall(hmem);
const activated = recall.recall({
  currentFile: 'src/auth/login.ts',
  currentCategory: 'security',
  recentEdits: ['src/auth/login.ts', 'src/middleware/auth.ts'],
  projectType: 'node',
  keywords: ['jwt', 'authentication', 'session'],
});

const consensus = new ConsensusEngine('my-agent');
const proposalId = consensus.propose('Use bcrypt cost factor 12', 'security', 0.95);

// Start everything
await brain.start();

Health Score System

Version History

Full changelogs, migration guides, and detailed release notes: docs/versions/

Compact changelog: CHANGELOG.md

Supported Agents & Tools

Development

git clone https://github.com/theihtisham/agent-shadow-brain.git
cd agent-shadow-brain
npm install
npm run build
npm test

Roadmap

• MCP Server, multi-project, team mode (v2.0)
• Cross-session neural mesh (v2.1)
• TurboQuant infinite memory (v4.0)
• SSSP quantum routing (v4.0)
• Self-evolving rules (v4.0)
• Cross-agent protocol (v4.0)
• Adversarial hallucination defense (v4.0)
• Hierarchical memory compression (v5.0)
• Context-triggered associative recall (v5.0)
• Multi-agent consensus protocol (v5.0)
• Collective cross-project learning (v5.0)
• Zero-config auto-setup (v5.0.1)
• MCP server for Cursor + all tools (v5.0.1)
• Rich web dashboard with real-time WebSocket (v5.0.1)
• Plugin system + brain export/import (v5.0.1)
• Custom LLM fine-tuning (v5.1.1)
• Language server (LSP) (v5.1.1)
• Web dashboard v3 (v5.1.1)
• Visual Studio Code integration — inline insight overlays
• Multi-model orchestration — route insights through multiple LLMs
• Real-time collaboration — team brain with live cursors

License

MIT License — see LICENSE for details.

Author

theihtisham