@theihtisham/agent-shadow-brain 5.2.0 → 6.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +225 -1029
- package/dist/brain/agent-firewall.d.ts +7 -0
- package/dist/brain/agent-firewall.d.ts.map +1 -0
- package/dist/brain/agent-firewall.js +152 -0
- package/dist/brain/agent-firewall.js.map +1 -0
- package/dist/brain/agent-handoff.d.ts +19 -0
- package/dist/brain/agent-handoff.d.ts.map +1 -0
- package/dist/brain/agent-handoff.js +127 -0
- package/dist/brain/agent-handoff.js.map +1 -0
- package/dist/brain/air-gap.d.ts +23 -0
- package/dist/brain/air-gap.d.ts.map +1 -0
- package/dist/brain/air-gap.js +137 -0
- package/dist/brain/air-gap.js.map +1 -0
- package/dist/brain/attention-heatmap.d.ts +24 -0
- package/dist/brain/attention-heatmap.d.ts.map +1 -0
- package/dist/brain/attention-heatmap.js +108 -0
- package/dist/brain/attention-heatmap.js.map +1 -0
- package/dist/brain/auto-setup.js +19 -14
- package/dist/brain/auto-setup.js.map +1 -1
- package/dist/brain/auto-update.js +1 -1
- package/dist/brain/brain-chat.d.ts +42 -0
- package/dist/brain/brain-chat.d.ts.map +1 -0
- package/dist/brain/brain-chat.js +162 -0
- package/dist/brain/brain-chat.js.map +1 -0
- package/dist/brain/brain-encryption.d.ts +14 -0
- package/dist/brain/brain-encryption.d.ts.map +1 -0
- package/dist/brain/brain-encryption.js +68 -0
- package/dist/brain/brain-encryption.js.map +1 -0
- package/dist/brain/brain-exchange.d.ts +30 -0
- package/dist/brain/brain-exchange.d.ts.map +1 -0
- package/dist/brain/brain-exchange.js +106 -0
- package/dist/brain/brain-exchange.js.map +1 -0
- package/dist/brain/brain-garden.d.ts +18 -0
- package/dist/brain/brain-garden.d.ts.map +1 -0
- package/dist/brain/brain-garden.js +81 -0
- package/dist/brain/brain-garden.js.map +1 -0
- package/dist/brain/brain-portability.js +1 -1
- package/dist/brain/branch-brain.d.ts +23 -0
- package/dist/brain/branch-brain.d.ts.map +1 -0
- package/dist/brain/branch-brain.js +159 -0
- package/dist/brain/branch-brain.js.map +1 -0
- package/dist/brain/calibration-monitor.d.ts +20 -0
- package/dist/brain/calibration-monitor.d.ts.map +1 -0
- package/dist/brain/calibration-monitor.js +144 -0
- package/dist/brain/calibration-monitor.js.map +1 -0
- package/dist/brain/causal-chains.d.ts +37 -0
- package/dist/brain/causal-chains.d.ts.map +1 -0
- package/dist/brain/causal-chains.js +250 -0
- package/dist/brain/causal-chains.js.map +1 -0
- package/dist/brain/collision-detective.d.ts +32 -0
- package/dist/brain/collision-detective.d.ts.map +1 -0
- package/dist/brain/collision-detective.js +233 -0
- package/dist/brain/collision-detective.js.map +1 -0
- package/dist/brain/cost-aware-spawner.d.ts +7 -0
- package/dist/brain/cost-aware-spawner.d.ts.map +1 -0
- package/dist/brain/cost-aware-spawner.js +77 -0
- package/dist/brain/cost-aware-spawner.js.map +1 -0
- package/dist/brain/dream-engine.d.ts +35 -0
- package/dist/brain/dream-engine.d.ts.map +1 -0
- package/dist/brain/dream-engine.js +273 -0
- package/dist/brain/dream-engine.js.map +1 -0
- package/dist/brain/embeddings.d.ts +27 -0
- package/dist/brain/embeddings.d.ts.map +1 -0
- package/dist/brain/embeddings.js +175 -0
- package/dist/brain/embeddings.js.map +1 -0
- package/dist/brain/forgetting-curve.d.ts +21 -0
- package/dist/brain/forgetting-curve.d.ts.map +1 -0
- package/dist/brain/forgetting-curve.js +174 -0
- package/dist/brain/forgetting-curve.js.map +1 -0
- package/dist/brain/formal-verification-bridge.d.ts +26 -0
- package/dist/brain/formal-verification-bridge.d.ts.map +1 -0
- package/dist/brain/formal-verification-bridge.js +219 -0
- package/dist/brain/formal-verification-bridge.js.map +1 -0
- package/dist/brain/global-brain.d.ts +8 -1
- package/dist/brain/global-brain.d.ts.map +1 -1
- package/dist/brain/global-brain.js +24 -0
- package/dist/brain/global-brain.js.map +1 -1
- package/dist/brain/hallucination-quarantine.d.ts +26 -0
- package/dist/brain/hallucination-quarantine.d.ts.map +1 -0
- package/dist/brain/hallucination-quarantine.js +135 -0
- package/dist/brain/hallucination-quarantine.js.map +1 -0
- package/dist/brain/hive-accelerator.d.ts +39 -0
- package/dist/brain/hive-accelerator.d.ts.map +1 -0
- package/dist/brain/hive-accelerator.js +152 -0
- package/dist/brain/hive-accelerator.js.map +1 -0
- package/dist/brain/json-output.d.ts +26 -0
- package/dist/brain/json-output.d.ts.map +1 -0
- package/dist/brain/json-output.js +112 -0
- package/dist/brain/json-output.js.map +1 -0
- package/dist/brain/l0-cache.js +1 -1
- package/dist/brain/l0-cache.js.map +1 -1
- package/dist/brain/local-llm.d.ts +20 -0
- package/dist/brain/local-llm.d.ts.map +1 -0
- package/dist/brain/local-llm.js +132 -0
- package/dist/brain/local-llm.js.map +1 -0
- package/dist/brain/mcp-server.d.ts +40 -0
- package/dist/brain/mcp-server.d.ts.map +1 -1
- package/dist/brain/mcp-server.js +395 -12
- package/dist/brain/mcp-server.js.map +1 -1
- package/dist/brain/model-registry.d.ts +96 -0
- package/dist/brain/model-registry.d.ts.map +1 -0
- package/dist/brain/model-registry.js +585 -0
- package/dist/brain/model-registry.js.map +1 -0
- package/dist/brain/orchestrator.js +1 -1
- package/dist/brain/pr-auto-review.d.ts +17 -0
- package/dist/brain/pr-auto-review.d.ts.map +1 -0
- package/dist/brain/pr-auto-review.js +73 -0
- package/dist/brain/pr-auto-review.js.map +1 -0
- package/dist/brain/pre-mortem.d.ts +21 -0
- package/dist/brain/pre-mortem.d.ts.map +1 -0
- package/dist/brain/pre-mortem.js +210 -0
- package/dist/brain/pre-mortem.js.map +1 -0
- package/dist/brain/prompt-cache.d.ts +54 -0
- package/dist/brain/prompt-cache.d.ts.map +1 -0
- package/dist/brain/prompt-cache.js +105 -0
- package/dist/brain/prompt-cache.js.map +1 -0
- package/dist/brain/reputation-ledger.d.ts +42 -0
- package/dist/brain/reputation-ledger.d.ts.map +1 -0
- package/dist/brain/reputation-ledger.js +326 -0
- package/dist/brain/reputation-ledger.js.map +1 -0
- package/dist/brain/session-hooks.d.ts +19 -0
- package/dist/brain/session-hooks.d.ts.map +1 -1
- package/dist/brain/session-hooks.js +249 -18
- package/dist/brain/session-hooks.js.map +1 -1
- package/dist/brain/subagent-bridge.d.ts +46 -0
- package/dist/brain/subagent-bridge.d.ts.map +1 -0
- package/dist/brain/subagent-bridge.js +364 -0
- package/dist/brain/subagent-bridge.js.map +1 -0
- package/dist/brain/swarm-debate.d.ts +22 -0
- package/dist/brain/swarm-debate.d.ts.map +1 -0
- package/dist/brain/swarm-debate.js +134 -0
- package/dist/brain/swarm-debate.js.map +1 -0
- package/dist/brain/team-brain-sync.d.ts +22 -0
- package/dist/brain/team-brain-sync.d.ts.map +1 -0
- package/dist/brain/team-brain-sync.js +132 -0
- package/dist/brain/team-brain-sync.js.map +1 -0
- package/dist/brain/token-economy.d.ts +25 -0
- package/dist/brain/token-economy.d.ts.map +1 -0
- package/dist/brain/token-economy.js +216 -0
- package/dist/brain/token-economy.js.map +1 -0
- package/dist/brain/voice-mode.d.ts +15 -0
- package/dist/brain/voice-mode.d.ts.map +1 -0
- package/dist/brain/voice-mode.js +97 -0
- package/dist/brain/voice-mode.js.map +1 -0
- package/dist/cli.js +823 -4
- package/dist/cli.js.map +1 -1
- package/dist/dashboard/server.d.ts +6 -0
- package/dist/dashboard/server.d.ts.map +1 -1
- package/dist/dashboard/server.js +1118 -368
- package/dist/dashboard/server.js.map +1 -1
- package/dist/dashboard/v6-dashboard-html.d.ts +2 -0
- package/dist/dashboard/v6-dashboard-html.d.ts.map +1 -0
- package/dist/dashboard/v6-dashboard-html.js +2474 -0
- package/dist/dashboard/v6-dashboard-html.js.map +1 -0
- package/dist/index.d.ts +27 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +29 -1
- package/dist/index.js.map +1 -1
- package/dist/types.d.ts +518 -2
- package/dist/types.d.ts.map +1 -1
- package/package.json +33 -4
package/README.md
CHANGED
|
@@ -1,1159 +1,355 @@
|
|
|
1
1
|
<div align="center">
|
|
2
2
|
|
|
3
|
-
<
|
|
3
|
+
<a href="https://github.com/theihtisham/agent-shadow-brain/raw/main/docs/launch/shadow-brain-motion-explainer-narrated.mp4">
|
|
4
|
+
<img src="Banner (2).png" alt="Shadow Brain v6.0 — Hive Mind · Click to watch the 2-minute explainer" width="100%">
|
|
5
|
+
</a>
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
### 🎬 **[▶ Watch the 2-minute explainer](https://github.com/theihtisham/agent-shadow-brain/raw/main/docs/launch/shadow-brain-motion-explainer-narrated.mp4)** · Click the banner above
|
|
6
8
|
|
|
7
9
|
[](https://www.npmjs.com/package/@theihtisham/agent-shadow-brain)
|
|
8
10
|
[](https://www.npmjs.com/package/@theihtisham/agent-shadow-brain)
|
|
9
|
-
[](https://www.npmjs.com/package/@theihtisham/agent-shadow-brain)
|
|
10
|
-
[](https://bundlephobia.com/package/@theihtisham/agent-shadow-brain)
|
|
11
|
-
[](https://github.com/theihtisham/agent-shadow-brain/blob/master/LICENSE)
|
|
12
|
-
[](https://nodejs.org/)
|
|
13
|
-
[](https://www.typescriptlang.org/)
|
|
14
11
|
[](https://github.com/theihtisham/agent-shadow-brain/stargazers)
|
|
15
|
-
[](#)
|
|
25
|
-
[](#-architecture)
|
|
26
|
-
[](#-cli-reference)
|
|
27
|
-
[](#)
|
|
28
|
-
[](#-1-singleton-global-brain)
|
|
29
|
-
[](#-2-subconscious-engine)
|
|
30
|
-
[](#-4-l0-sub-millisecond-cache)
|
|
31
|
-
[](#-3-universal-bootstrap-attach-all)
|
|
32
|
-
[](#)
|
|
33
|
-
[](#)
|
|
34
|
-
[](https://github.com/theihtisham/agent-shadow-brain/pulls)
|
|
35
|
-
[](#)
|
|
36
|
-
[](https://github.com/theihtisham)
|
|
12
|
+
[](https://github.com/theihtisham/agent-shadow-brain/blob/main/LICENSE)
|
|
13
|
+
[](https://www.typescriptlang.org/)
|
|
14
|
+
[](https://nodejs.org/)
|
|
15
|
+
[](#-architecture)
|
|
16
|
+
[](#-cli-reference)
|
|
17
|
+
[](#-mcp-tools)
|
|
18
|
+
[](#)
|
|
19
|
+
[](#)
|
|
20
|
+
[](#)
|
|
37
21
|
|
|
38
22
|
<br/>
|
|
39
23
|
|
|
40
|
-
|
|
24
|
+
# 🧠 Shadow Brain v6.0 — Hive Mind
|
|
41
25
|
|
|
42
|
-
|
|
26
|
+
### *The first open-source brain that every AI coding agent on your machine can share.*
|
|
43
27
|
|
|
44
|
-
|
|
28
|
+
**Claude Code · Cursor · Cline · Codex · Copilot · Windsurf · Kilo · Roo · OpenCode · Aider** — all running on one local brain. What one agent learns, every agent knows. What one sub-agent discovers, every sub-agent inherits.
|
|
45
29
|
|
|
46
30
|
```bash
|
|
47
|
-
# 30
|
|
48
|
-
npx @theihtisham/agent-shadow-brain attach-all
|
|
31
|
+
# 30 seconds. Every agent + sub-agent on your machine becomes smarter.
|
|
32
|
+
npx @theihtisham/agent-shadow-brain@latest attach-all
|
|
49
33
|
```
|
|
50
34
|
|
|
51
|
-
[
|
|
35
|
+
**[🎬 Video](https://github.com/theihtisham/agent-shadow-brain/raw/main/docs/launch/shadow-brain-motion-explainer-narrated.mp4) · [📦 npm](https://www.npmjs.com/package/@theihtisham/agent-shadow-brain) · [⭐ Star on GitHub](https://github.com/theihtisham/agent-shadow-brain) · [📚 Docs](https://github.com/theihtisham/agent-shadow-brain/tree/main/docs) · [🐛 Issues](https://github.com/theihtisham/agent-shadow-brain/issues)**
|
|
52
36
|
|
|
53
37
|
</div>
|
|
54
38
|
|
|
55
39
|
---
|
|
56
40
|
|
|
57
|
-
## ⚡
|
|
58
|
-
|
|
59
|
-
| Without Shadow Brain | With Shadow Brain |
|
|
60
|
-
|---|---|
|
|
61
|
-
| Every new session, your agent starts from zero | Agent gets a 2K-token briefing of relevant context **before it asks** |
|
|
62
|
-
| Cursor learns something — Claude doesn't know | One singleton brain — what one agent learns, all agents know |
|
|
63
|
-
| Discoveries in project A don't help project B | Cross-project memory federation by default |
|
|
64
|
-
| Each AI tool needs its own setup | One command attaches every agent |
|
|
65
|
-
| Agents hallucinate APIs that don't exist | Adversarial defense + multi-agent consensus voting |
|
|
66
|
-
| Your codebase patterns are reinvented daily | Code DNA fingerprinting enforces your style across all agents |
|
|
67
|
-
| 30 minutes of config before anything works | Zero config, auto-detect, instant value |
|
|
68
|
-
|
|
69
|
-
## 🚀 v5.2.0 — What Makes It Singular
|
|
70
|
-
|
|
71
|
-
### 🧠 1. Singleton Global Brain
|
|
72
|
-
|
|
73
|
-
One database (`~/.shadow-brain/global.db`) is the **source of truth** for every project and every agent on your machine. Project-scoped views give each project its own namespace, but the data lives in one place. SQLite WAL mode + write queue handle concurrent multi-agent writes safely. Auto-vacuum at 500MB, auto-prune at 1GB.
|
|
74
|
-
|
|
75
|
-
```bash
|
|
76
|
-
shadow-brain global stats # See cross-project, cross-agent stats
|
|
77
|
-
shadow-brain global recall # Search across every project + every agent
|
|
78
|
-
```
|
|
79
|
-
|
|
80
|
-
### 💭 2. Subconscious Engine
|
|
81
|
-
|
|
82
|
-
Every time any agent starts a new session, the Subconscious **proactively injects** a tight briefing of:
|
|
83
|
-
- Recent decisions made in this project (last 24h)
|
|
84
|
-
- Active tasks (TODOs, in-progress items)
|
|
85
|
-
- Similar past work from other projects
|
|
86
|
-
- Cross-agent insights (what Claude learned that Cursor should know)
|
|
87
|
-
- Warnings and known pitfalls
|
|
88
|
-
|
|
89
|
-
Hard-capped at 2K tokens. Relevance-ranked. The agent doesn't have to ask — the brain surfaces it implicitly. Like human intuition.
|
|
90
|
-
|
|
91
|
-
```bash
|
|
92
|
-
shadow-brain subconscious inject # See what your agent gets
|
|
93
|
-
shadow-brain subconscious configure --budget 3000 # Tune the budget
|
|
94
|
-
```
|
|
95
|
-
|
|
96
|
-
### 🪝 3. Universal Bootstrap (`attach-all`)
|
|
97
|
-
|
|
98
|
-
One command. Detects every AI agent installed on your machine. Installs the right hook for each one's native mechanism:
|
|
99
|
-
|
|
100
|
-
| Agent | Hook Mechanism |
|
|
101
|
-
|---|---|
|
|
102
|
-
| **Claude Code** | `~/.claude/settings.json` → `hooks.SessionStart` |
|
|
103
|
-
| **Cursor** | `.cursor/rules/shadow-brain.md` + `.cursor/mcp.json` |
|
|
104
|
-
| **Cline** | `~/.vscode/.../cline_mcp_settings.json` |
|
|
105
|
-
| **Windsurf** | `.windsurfrules` + `~/.windsurf/mcp.json` |
|
|
106
|
-
| **Codex** | `~/.codex/config.json` |
|
|
107
|
-
| **Kilo Code** | `~/.kilocode/settings.json` |
|
|
108
|
-
| **OpenCode** | `~/.opencode/settings.json` |
|
|
109
|
-
| **Roo Code** | `~/.roocode/mcp.json` |
|
|
110
|
-
| **Aider** | `~/.aider.conf.yml` `read:` directive |
|
|
111
|
-
| **GitHub Copilot** | `.github/copilot-instructions.md` |
|
|
41
|
+
## ⚡ Install in 30 seconds
|
|
112
42
|
|
|
113
43
|
```bash
|
|
114
|
-
|
|
115
|
-
shadow-brain attach-all
|
|
116
|
-
```
|
|
44
|
+
# Method 1 — one command, every agent wired, dashboard launches
|
|
45
|
+
npx @theihtisham/agent-shadow-brain@latest attach-all
|
|
117
46
|
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
47
|
+
# Method 2 — global install
|
|
48
|
+
npm install -g @theihtisham/agent-shadow-brain
|
|
49
|
+
shadow-brain attach-all
|
|
50
|
+
shadow-brain dash . # → http://localhost:7341/
|
|
121
51
|
|
|
122
|
-
|
|
123
|
-
|
|
52
|
+
# Method 3 — in a specific project only
|
|
53
|
+
cd my-project
|
|
54
|
+
npx @theihtisham/agent-shadow-brain attach-all
|
|
124
55
|
```
|
|
125
56
|
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
Cursor, Windsurf, and Copilot were stub aliases in v5.1.1. In v5.2.0 they each have **dedicated adapters** matching their actual file layouts, conversation parsers, and injection mechanisms.
|
|
129
|
-
|
|
130
|
-
---
|
|
57
|
+
**Zero config. Zero API key required. 100 % local-first.**
|
|
131
58
|
|
|
132
59
|
---
|
|
133
60
|
|
|
134
|
-
##
|
|
61
|
+
## 🔥 Why Shadow Brain? (the 60-second pitch)
|
|
135
62
|
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
| Problem | Impact |
|
|
63
|
+
| Without Shadow Brain | With Shadow Brain v6 |
|
|
139
64
|
|---|---|
|
|
140
|
-
|
|
|
141
|
-
|
|
|
142
|
-
|
|
|
143
|
-
|
|
|
144
|
-
|
|
|
145
|
-
|
|
|
146
|
-
|
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
**Shadow Brain v5.1.1** — zero-config, auto-detecting, infinite-intelligence shadow layer:
|
|
151
|
-
|
|
152
|
-
```
|
|
153
|
-
┌──────────────┐ auto-detect ┌──────────────────────────────────────────┐
|
|
154
|
-
│ AI Agents │ ◀──────────────── │ SHADOW BRAIN v5.1.1 │
|
|
155
|
-
│ Claude Code │ MCP auto-install │ │
|
|
156
|
-
│ Cursor │ zero-config │ ┌─ HYPER-COGNITIVE (v5.1.1 NEW) ────┐ │
|
|
157
|
-
│ Kilo Code │ │ │ Built-in LSP Server (stdio+TCP) │ │
|
|
158
|
-
│ Cline │ watches │ │ Custom LLM Fine-Tuning Engine │ │
|
|
159
|
-
│ OpenCode │ ──────────────▶ │ │ Smart Cache (hot/warm/cold tiers) │ │
|
|
160
|
-
│ Codex │ file changes │ │ Intent Engine (NLP commands) │ │
|
|
161
|
-
│ Roo Code │ git commits │ │ Code DNA (9-gene fingerprinting) │ │
|
|
162
|
-
│ Aider │ activity │ │ Temporal Intelligence (velocity) │ │
|
|
163
|
-
│ Windsurf │ │ └────────────────────────────────────┘ │
|
|
164
|
-
└──────────────┘ │ ┌─ ZERO-CONFIG (v5.0.1) ─────────────┐ │
|
|
165
|
-
▲ │ │ Auto-detect + MCP + Dashboard │ │
|
|
166
|
-
│ │ │ Plugins + Export/Import + Hooks │ │
|
|
167
|
-
│ │ └────────────────────────────────────┘ │
|
|
168
|
-
│ │ ┌─ INFINITE MEMORY (v5.0.0) ────────┐ │
|
|
169
|
-
│ │ │ 4-tier hierarchical compression │ │
|
|
170
|
-
│ │ │ Context-triggered recall │ │
|
|
171
|
-
│ │ │ Multi-agent consensus + trust │ │
|
|
172
|
-
│ │ │ Collective cross-project learning │ │
|
|
173
|
-
│ │ └────────────────────────────────────┘ │
|
|
174
|
-
│ │ ┌─ HYPER-INTELLIGENCE (v4) ──────────┐ │
|
|
175
|
-
│ │ │ TurboQuant 6x Compression │ │
|
|
176
|
-
│ │ │ SSSP BMSSP Quantum Routing │ │
|
|
177
|
-
│ │ │ Self-Evolution + CAIP + Swarm │ │
|
|
178
|
-
│ │ │ PageRank + Predictive + Adversarial │ │
|
|
179
|
-
└──────────────────────────┴──────────────────────────────────────────┘
|
|
180
|
-
```
|
|
65
|
+
| Every new session → agent starts from zero | 2K-token briefing injected **before** the first prompt |
|
|
66
|
+
| Cursor learns X → Claude doesn't know | **One singleton brain** every agent shares |
|
|
67
|
+
| Claude Task spawns sub-agent → sub-agent starts blind | **SABB** injects focused context slivers into every sub-agent |
|
|
68
|
+
| You can't explain *why* the AI made a choice | **Causal Memory Chains** render the full DAG of causes |
|
|
69
|
+
| Two agents touching the same file = merge hell | **Collision Detective** catches it in real time |
|
|
70
|
+
| Agents work, then go idle — wasted compute | **Dream Engine** reflects during idle, runs counterfactuals |
|
|
71
|
+
| No verifiable record of agent decisions | **Ed25519-signed Reputation Ledger** — tamper-proof receipts |
|
|
72
|
+
| Token bills explode across Opus / GPT / Gemini | **Token Economy** routes to cheapest model that passes confidence |
|
|
73
|
+
| Needs its own API key for everything | **Agent-proxy mode** reuses your existing Claude/Cursor/Codex config |
|
|
74
|
+
| Every tool runs hot, every key leaks | **Air-Gap mode** + ChaCha20 encryption at rest |
|
|
181
75
|
|
|
182
76
|
---
|
|
183
77
|
|
|
184
|
-
##
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
**
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
**
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
</td>
|
|
224
|
-
<td width="50%">
|
|
225
|
-
|
|
226
|
-
### Smart Cache (Multi-Tier)
|
|
227
|
-
|
|
228
|
-
**Hot/Warm/Cold** — intelligent caching with predictive prefetch.
|
|
229
|
-
|
|
230
|
-
Three-tier LRU cache with automatic promotion and demotion:
|
|
231
|
-
- **Hot tier**: 200 entries, fastest access
|
|
232
|
-
- **Warm tier**: 1000 entries, promoted on repeated access
|
|
233
|
-
- **Cold tier**: 5000 entries, compressed storage
|
|
234
|
-
- **Predictive prefetch**: co-access graph predicts what you'll need next
|
|
235
|
-
- **Tag-based invalidation**: invalidate by category
|
|
236
|
-
|
|
237
|
-
```bash
|
|
238
|
-
shadow-brain cache stats # Hit rate, tier sizes, memory usage
|
|
239
|
-
shadow-brain cache clear # Clear all tiers
|
|
240
|
-
```
|
|
241
|
-
|
|
242
|
-
### Intent Engine
|
|
243
|
-
|
|
244
|
-
**Natural language → brain actions** — understand what you mean.
|
|
245
|
-
|
|
246
|
-
Multi-strategy NLP command understanding:
|
|
247
|
-
- **Keyword matching**: fast path for common commands
|
|
248
|
-
- **Fuzzy matching**: handles typos and variations
|
|
249
|
-
- **Context-aware**: uses current file/project context
|
|
250
|
-
- **Confidence scoring**: routes to best-matching action
|
|
251
|
-
|
|
252
|
-
```bash
|
|
253
|
-
shadow-brain intent "find security bugs" # Maps to: analyze + security filter
|
|
254
|
-
shadow-brain intent "show hot files" # Maps to: temporal + heatmap
|
|
255
|
-
```
|
|
256
|
-
|
|
257
|
-
</td>
|
|
258
|
-
</tr>
|
|
259
|
-
<tr>
|
|
260
|
-
<td width="50%">
|
|
261
|
-
|
|
262
|
-
### Code DNA Fingerprinting
|
|
263
|
-
|
|
264
|
-
**9-gene analysis** — every file gets a unique genetic profile.
|
|
265
|
-
|
|
266
|
-
Analyzes code across 9 gene categories to create a structural fingerprint:
|
|
267
|
-
- **Structure genes**: classes, functions, nesting depth
|
|
268
|
-
- **Complexity genes**: cyclomatic complexity, cognitive load
|
|
269
|
-
- **Style genes**: naming conventions, formatting patterns
|
|
270
|
-
- **Dependency genes**: import graph, coupling metrics
|
|
271
|
-
- **Evolution genes**: change frequency, stability score
|
|
272
|
-
- **Similarity matching**: find structurally similar files across projects
|
|
273
|
-
|
|
274
|
-
```bash
|
|
275
|
-
shadow-brain dna analyze [dir] # Generate DNA profiles
|
|
276
|
-
shadow-brain dna compare f1 f2 # Compare two file fingerprints
|
|
277
|
-
shadow-brain dna similar [file] # Find similar files
|
|
278
|
-
```
|
|
279
|
-
|
|
280
|
-
</td>
|
|
281
|
-
<td width="50%">
|
|
282
|
-
|
|
283
|
-
### Temporal Intelligence
|
|
284
|
-
|
|
285
|
-
**Time-series code evolution** — velocity tracking & bug prediction.
|
|
286
|
-
|
|
287
|
-
Continuous monitoring of code change patterns over time:
|
|
288
|
-
- **Velocity metrics**: daily/weekly/monthly rates with trend detection
|
|
289
|
-
- **File heatmaps**: hotness scoring, churn risk, stability
|
|
290
|
-
- **Bug prediction**: 5-factor probability model per file
|
|
291
|
-
- **Anomaly detection**: burst detection, drought alerts, unusual hours
|
|
292
|
-
- **Peak analysis**: identifies your most productive hours and days
|
|
293
|
-
|
|
294
|
-
```bash
|
|
295
|
-
shadow-brain temporal stats # Velocity, anomalies, predictions
|
|
296
|
-
shadow-brain temporal hot # Top 10 hottest files
|
|
297
|
-
shadow-brain temporal predict # Bug risk predictions
|
|
298
|
-
shadow-brain temporal timeline # Recent event timeline
|
|
299
|
-
```
|
|
300
|
-
|
|
301
|
-
</td>
|
|
302
|
-
</tr>
|
|
303
|
-
</table>
|
|
78
|
+
## 🌟 22 Novel Modules — None Exist in Any Other Tool
|
|
79
|
+
|
|
80
|
+
> *This isn't a wrapper around someone else's API. All 22 are first-party research-grade implementations, persisted to disk, with real tests.*
|
|
81
|
+
|
|
82
|
+
### 🧠 Cognition
|
|
83
|
+
1. **Sub-Agent Brain Bridge (SABB)** — sync brain context into Claude Task / Cursor Composer / CrewAI / LangGraph / AutoGen sub-agents
|
|
84
|
+
2. **Causal Memory Chains** — every decision links to its causes; Graphviz DOT export
|
|
85
|
+
3. **Dream Engine** — idle-time reflection: revisit / counterfactual / consolidation / contradiction / pattern-discovery
|
|
86
|
+
4. **Swarm Debate Protocol** — pro / con / arbiter sub-agents for critical decisions
|
|
87
|
+
5. **Pre-Mortem Assistant** — surfaces past failures from *your* project before you start
|
|
88
|
+
6. **Branch Brains** — git-branch-aware memory context
|
|
89
|
+
|
|
90
|
+
### 🔍 Transparency & Trust
|
|
91
|
+
7. **Agent Reputation Ledger** — Ed25519-signed receipts, portable accuracy score
|
|
92
|
+
8. **Attention Heatmap** — weighted attribution showing which memories shaped a decision
|
|
93
|
+
9. **Confidence Calibration Monitor** — Brier scores + automatic trust-weighting
|
|
94
|
+
10. **Formal Verification Bridge** — natural-language rules → ESLint / Semgrep / LSP diagnostics
|
|
95
|
+
11. **Agent Collision Detective** — real-time overlap detection with advisory locks
|
|
96
|
+
|
|
97
|
+
### 💰 Economy & Memory
|
|
98
|
+
12. **Token Economy Engine** — cross-agent spend, savings suggestions, routing advice
|
|
99
|
+
13. **Cost-Aware Sub-Agent Spawner** — auto-route trivial tasks to cheaper models
|
|
100
|
+
14. **Forgetting Curve + Sleep Consolidation** — Ebbinghaus-inspired biological memory
|
|
101
|
+
|
|
102
|
+
### 🔒 Privacy & Safety
|
|
103
|
+
15. **Air-Gap Mode** — zero outbound network, localhost-only
|
|
104
|
+
16. **E2E Encryption** — ChaCha20-Poly1305 at rest
|
|
105
|
+
17. **Hallucination Quarantine** — isolate suspect memories, auto-expire in 7 days
|
|
106
|
+
|
|
107
|
+
### ✨ Delight & Network Effects
|
|
108
|
+
18. **Voice Mode** — natural-language intent parser for transcripts
|
|
109
|
+
19. **Brain Garden** — animated visualization of memory as a living constellation
|
|
110
|
+
20. **PR Auto-Review** — GitHub PR comments citing project memories
|
|
111
|
+
21. **Team Brain Sync (WebRTC)** — peer-to-peer shared brain, no server
|
|
112
|
+
22. **Brain Exchange** — export / import curated shareable brain slices
|
|
113
|
+
|
|
114
|
+
### ⚡ Accelerators
|
|
115
|
+
- **Local-First LLM** — Ollama default; optional Anthropic / OpenAI / OpenRouter / Moonshot / Gemini / DeepSeek / Mistral
|
|
116
|
+
- **Hive Accelerator** — SSSP ([arXiv 2504.17033](https://arxiv.org/abs/2504.17033)) + TurboQuant ([ICLR 2026](https://openreview.net/forum?id=TbqSEUXWaO)) for fast causal traversal + 6× vector compression
|
|
304
117
|
|
|
305
118
|
---
|
|
306
119
|
|
|
307
|
-
##
|
|
308
|
-
|
|
309
|
-
### Zero-Config Auto-Setup
|
|
310
|
-
|
|
311
|
-
Install it. That's it. Shadow Brain automatically:
|
|
312
|
-
|
|
313
|
-
- Detects your project type (frontend, backend, fullstack, mobile, game, systems, data-science)
|
|
314
|
-
- Detects 25+ languages, 15+ frameworks, 5+ build tools, 5+ test frameworks
|
|
315
|
-
- Detects which AI tools are installed (Claude Code, Cursor, Kilo Code, Cline, OpenCode, Codex, Aider, Windsurf)
|
|
316
|
-
- Auto-installs MCP server configuration for every detected AI tool
|
|
317
|
-
- Auto-installs git pre-commit and pre-push hooks
|
|
318
|
-
- Generates an optimal brain config based on project complexity
|
|
319
|
-
|
|
320
|
-
```bash
|
|
321
|
-
npm install @theihtisham/agent-shadow-brain
|
|
322
|
-
# → Shadow Brain v5.1.1 auto-configured for my-app (fullstack)
|
|
323
|
-
# → AI tools detected: Claude Code, Cursor
|
|
324
|
-
# → Run: shadow-brain start
|
|
325
|
-
```
|
|
326
|
-
|
|
327
|
-
### MCP Server — Works with EVERY AI Tool
|
|
328
|
-
|
|
329
|
-
The brain exposes itself as a **Model Context Protocol (MCP) server** with 19 tools that any AI tool can call:
|
|
330
|
-
|
|
331
|
-
| MCP Tool | What It Does |
|
|
332
|
-
|---|---|
|
|
333
|
-
| `brain_status` | Get full brain status |
|
|
334
|
-
| `brain_analyze` | Trigger code analysis |
|
|
335
|
-
| `brain_health` | Get health score (A-F) |
|
|
336
|
-
| `brain_insights` | Get recent insights |
|
|
337
|
-
| `brain_fixes` | Get smart fix suggestions |
|
|
338
|
-
| `brain_memory_store` | Store knowledge in hierarchical memory |
|
|
339
|
-
| `brain_memory_search` | Search across all memory tiers |
|
|
340
|
-
| `brain_memory_stats` | Memory compression statistics |
|
|
341
|
-
| `brain_recall` | Context-triggered associative recall |
|
|
342
|
-
| `brain_consensus_propose` | Submit a proposal for agent consensus |
|
|
343
|
-
| `brain_consensus_vote` | Vote on a pending proposal |
|
|
344
|
-
| `brain_collective_propose` | Propose a cross-project rule |
|
|
345
|
-
| `brain_collective_search` | Search collective learning rules |
|
|
346
|
-
| `brain_turbo_search` | Semantic search in compressed memory |
|
|
347
|
-
| `brain_predict` | Predict bug risk for files |
|
|
348
|
-
| `brain_graph_query` | Query knowledge graph |
|
|
349
|
-
| `brain_defense_scan` | Scan for hallucination patterns |
|
|
350
|
-
| `brain_evolve_status` | Get self-evolution status |
|
|
351
|
-
| `brain_dashboard_url` | Get dashboard URL |
|
|
352
|
-
|
|
353
|
-
Works with **Claude Code**, **Cursor**, **Kilo Code**, **Cline**, **OpenCode**, and any MCP-compatible AI tool.
|
|
120
|
+
## 🖥️ Complete Web Control Dashboard
|
|
354
121
|
|
|
122
|
+
Start it:
|
|
355
123
|
```bash
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
# Cursor compatibility (root path POST + /v1/chat)
|
|
360
|
-
# Claude Code compatibility (JSON-RPC 2.0 over stdio/HTTP)
|
|
124
|
+
shadow-brain dash .
|
|
125
|
+
# → http://localhost:7341/
|
|
361
126
|
```
|
|
362
127
|
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
Real-time browser dashboard at `http://localhost:7341` with WebSocket live updates:
|
|
366
|
-
|
|
367
|
-
- **Stats Topbar**: 8 live counters — Insights, Fixes, Memory KB, Modules, AI Tools, Evolution Gen, Swarm Convergence, Turbo Compression
|
|
368
|
-
- **Health Score**: A-F grading with dimension breakdown (Security, Quality, Performance, Architecture, Maintainability, Test Coverage)
|
|
369
|
-
- **Memory Tiers**: Visual bars showing Raw (50K), Summary (10K), Pattern (2K), Principle (500) with Turbo compression ratio
|
|
370
|
-
- **Live Insights Stream**: Real-time feed of brain insights with priority badges
|
|
371
|
-
- **Smart Fixes**: Actionable fix suggestions with file/line references
|
|
372
|
-
- **AI Tools Panel**: 8 tools showing connected/detected status
|
|
373
|
-
- **Brain Modules**: 13 modules with active/idle/error indicators
|
|
374
|
-
- **Control Buttons**: Trigger analysis on-demand, refresh data
|
|
375
|
-
|
|
376
|
-
```bash
|
|
377
|
-
shadow-brain start . # Dashboard auto-starts at http://localhost:7341
|
|
378
|
-
shadow-brain dash . # Dashboard only mode
|
|
379
|
-
```
|
|
128
|
+
**28 tabs. Real-time data. Full control.** Every feature has live monitoring + interactive controls. Preview:
|
|
380
129
|
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
130
|
+
| | | |
|
|
131
|
+
|---|---|---|
|
|
132
|
+
|  |  |  |
|
|
133
|
+
| **Overview** — live counters, charts | **Live Graph** — animated signal flow | **Agents** — connect / disconnect per agent |
|
|
134
|
+
|  |  |  |
|
|
135
|
+
| **Chat with Brain** — RAG with citations | **Memory Browser** — semantic search | **SABB** — sliver generator + quarantine |
|
|
136
|
+
|  |  |  |
|
|
137
|
+
| **Causal Chains** — traceable decisions | **Dream Engine** — reflection insights | **Reputation** — Ed25519 leaderboard |
|
|
138
|
+
|  |  |  |
|
|
139
|
+
| **Token Economy** — $ saved live | **Models & Intelligence** — 8 providers | **⌘K Command Palette** |
|
|
390
140
|
|
|
391
|
-
|
|
141
|
+
**→ [Browse all 29 tab screenshots](docs/launch/screenshots/)**
|
|
392
142
|
|
|
393
|
-
|
|
143
|
+
Features: dark + light theme · command palette (⌘K) · keyboard shortcuts · toast notifications · Chart.js analytics · responsive (mobile / tablet / desktop) · real-time WebSocket · stop button that actually stops the process.
|
|
394
144
|
|
|
395
|
-
|
|
396
|
-
shadow-brain export # Full export with all modules
|
|
397
|
-
shadow-brain export -o ./team-brain # Custom output directory
|
|
398
|
-
shadow-brain import brain-export.json # Import + merge
|
|
399
|
-
shadow-brain import brain-export.json --merge --skip swarm,evolution
|
|
400
|
-
```
|
|
401
|
-
|
|
402
|
-
### Plugin System
|
|
145
|
+
---
|
|
403
146
|
|
|
404
|
-
|
|
147
|
+
## 🧩 Works With Every AI Coding Agent
|
|
405
148
|
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
shadow-brain
|
|
410
|
-
|
|
149
|
+
| Agent | Adapter | Hook target |
|
|
150
|
+
|---|---|---|
|
|
151
|
+
| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | ✅ Native | `~/.claude/settings.json` hooks.SessionStart |
|
|
152
|
+
| [Cursor](https://cursor.sh/) | ✅ Native | `.cursor/rules/shadow-brain.md` + MCP |
|
|
153
|
+
| [Cline](https://github.com/cline/cline) | ✅ Native | VS Code globalStorage MCP |
|
|
154
|
+
| [Codex](https://github.com/openai/codex) | ✅ Native | `~/.codex/config.json` |
|
|
155
|
+
| [GitHub Copilot](https://github.com/features/copilot) | ✅ Native | `.github/copilot-instructions.md` |
|
|
156
|
+
| [Windsurf](https://codeium.com/windsurf) | ✅ Native | `.windsurfrules` + MCP |
|
|
157
|
+
| [Kilo Code](https://kilocode.ai/) | ✅ Native | `~/.kilocode/settings.json` |
|
|
158
|
+
| [Roo Code](https://roocode.com/) | ✅ Native | `~/.roocode/mcp.json` |
|
|
159
|
+
| [OpenCode](https://github.com/opencode-ai/opencode) | ✅ Native | `AGENT.md` |
|
|
160
|
+
| [Aider](https://aider.chat/) | ✅ Native | `.aider.conf.yml` |
|
|
411
161
|
|
|
412
|
-
|
|
162
|
+
**Custom agent?** Add its config path in the dashboard "Custom Agent Paths" panel — Shadow Brain will auto-read its provider + model + API key.
|
|
413
163
|
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
```bash
|
|
417
|
-
shadow-brain off # Clean shutdown
|
|
418
|
-
shadow-brain ask "..." # Natural language query
|
|
419
|
-
shadow-brain export # Export brain state
|
|
420
|
-
shadow-brain import FILE # Import brain state
|
|
421
|
-
shadow-brain plugin CMD # Plugin management
|
|
422
|
-
```
|
|
164
|
+
**Sub-agent frameworks supported by SABB:** Claude Task, Cursor Composer, Cline Sub-step, CrewAI, LangGraph, AutoGen, generic.
|
|
423
165
|
|
|
424
166
|
---
|
|
425
167
|
|
|
426
|
-
##
|
|
168
|
+
## 🤖 Use Your Own LLM — or Your Agent's Already-Configured One
|
|
427
169
|
|
|
428
|
-
|
|
429
|
-
# Install globally
|
|
430
|
-
npm install -g @theihtisham/agent-shadow-brain
|
|
170
|
+
Shadow Brain's **ModelRegistry** supports 8 providers out of the box:
|
|
431
171
|
|
|
432
|
-
|
|
433
|
-
npx @theihtisham/agent-shadow-brain start .
|
|
434
|
-
```
|
|
172
|
+
**Ollama (default, local, free)** · **Anthropic Claude** · **OpenAI** · **OpenRouter** · **Moonshot / Kimi** · **Google Gemini** · **DeepSeek** · **Mistral**
|
|
435
173
|
|
|
436
|
-
|
|
437
|
-
1. **Auto-detect** your project, languages, frameworks, AI tools (zero config)
|
|
438
|
-
2. **Auto-install** MCP server config for Claude Code, Cursor, Kilo Code, Cline, etc.
|
|
439
|
-
3. **Auto-install** git hooks for pre-commit and pre-push
|
|
440
|
-
4. Watch your project files for changes
|
|
441
|
-
5. Analyze every change with LLM + 22 brain modules
|
|
442
|
-
6. Inject expert insights into your agent's memory
|
|
443
|
-
7. Store all knowledge in hierarchical memory for infinite retention
|
|
444
|
-
8. Activate past memories automatically based on context
|
|
445
|
-
9. Share verified patterns across projects via collective learning
|
|
446
|
-
10. Compress knowledge with TurboQuant for infinite retention
|
|
447
|
-
11. Evolve its own rules via genetic algorithm
|
|
448
|
-
12. Share insights across agents via CAIP
|
|
449
|
-
13. Detect hallucinations with adversarial verification
|
|
450
|
-
14. Run consensus when multiple agents disagree
|
|
451
|
-
15. Serve a rich web dashboard at `localhost:7341`
|
|
452
|
-
|
|
453
|
-
### Quick Review (No Watch Mode)
|
|
174
|
+
Plus a unique **Agent Proxy** mode: if you already use Claude Code / Cursor / Codex with their own API key, Shadow Brain borrows their intelligence — **zero new API keys, zero cost**.
|
|
454
175
|
|
|
455
|
-
|
|
456
|
-
shadow-brain review . # One-shot analysis
|
|
457
|
-
shadow-brain review . --show-health # + health score
|
|
458
|
-
shadow-brain review . --show-fixes # + fix suggestions
|
|
459
|
-
shadow-brain review . --output json # JSON for scripting
|
|
460
|
-
```
|
|
176
|
+
Auto-discovery reads every agent config on your machine so you never retype a key.
|
|
461
177
|
|
|
462
178
|
---
|
|
463
179
|
|
|
464
|
-
##
|
|
180
|
+
## 📊 Real Numbers
|
|
465
181
|
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
│ Arch: B │ │ ● OpenCode — │
|
|
480
|
-
│ Maintain: A ├─────────────────────────────────────┤ ● Codex — │
|
|
481
|
-
│ Tests: C+ │ Smart Fixes │ ● Aider — │
|
|
482
|
-
│ │ 1. Add parameterized query... │ ● Windsurf — │
|
|
483
|
-
├──────────────┤ 2. Wrap in try/catch with... ├───────────────────┤
|
|
484
|
-
│ Memory Tiers │ 3. Remove unused import on L42 │ Brain Modules │
|
|
485
|
-
│ Raw: 8421 │ │ ● Hierarchical ✓ │
|
|
486
|
-
│ Summ: 1203 │ │ ● TurboMemory ✓ │
|
|
487
|
-
│ Patt: 187 │ │ ● Consensus ✓ │
|
|
488
|
-
│ Princ: 24 │ │ ● Swarm ✓ │
|
|
489
|
-
│ Turbo: 6.2x │ │ ● Evolution ✓ │
|
|
490
|
-
│ │ │ ● Adversarial ✓ │
|
|
491
|
-
└──────────────┴─────────────────────────────────────┴───────────────────┘
|
|
492
|
-
```
|
|
182
|
+
| Metric | Value |
|
|
183
|
+
|---|---|
|
|
184
|
+
| Brain modules | **48** |
|
|
185
|
+
| CLI commands | **90+** |
|
|
186
|
+
| MCP tools | **60+** |
|
|
187
|
+
| REST endpoints | **50+** |
|
|
188
|
+
| Tests passing | **148 / 148** |
|
|
189
|
+
| TypeScript errors | **0** |
|
|
190
|
+
| Supported agents | **10** (plus custom) |
|
|
191
|
+
| Supported LLM providers | **8** (plus agent-proxy) |
|
|
192
|
+
| Novel features nobody else has | **22** |
|
|
193
|
+
| License | **MIT** |
|
|
194
|
+
| Cost to run | **$0 forever** (local-first) |
|
|
493
195
|
|
|
494
196
|
---
|
|
495
197
|
|
|
496
|
-
##
|
|
497
|
-
|
|
498
|
-
### 4 Breakthrough Modules
|
|
499
|
-
|
|
500
|
-
<table>
|
|
501
|
-
<tr>
|
|
502
|
-
<td width="50%">
|
|
503
|
-
|
|
504
|
-
### Infinite Memory Layer
|
|
505
|
-
|
|
506
|
-
**Hierarchical Memory Compression** — 4-tier pyramid that never forgets.
|
|
507
|
-
|
|
508
|
-
Knowledge flows through compression tiers as it ages:
|
|
509
|
-
- **Raw** (50K entries) — full detail, hot path
|
|
510
|
-
- **Summary** (10K) — condensed key points
|
|
511
|
-
- **Pattern** (2K) — recurring patterns extracted
|
|
512
|
-
- **Principle** (500) — timeless design rules
|
|
513
|
-
|
|
514
|
-
Drill-down and drill-up between tiers. Older knowledge compresses, never deletes.
|
|
515
|
-
|
|
516
|
-
```bash
|
|
517
|
-
shadow-brain memory stats # 4 tiers | 12,847 entries
|
|
518
|
-
shadow-brain memory store "..." # Store new knowledge
|
|
519
|
-
shadow-brain memory search "auth" # Cross-tier semantic search
|
|
520
|
-
```
|
|
521
|
-
|
|
522
|
-
**Context-Triggered Associative Recall** — memories that activate themselves.
|
|
523
|
-
|
|
524
|
-
Instead of requiring explicit search queries, this engine monitors your current work context and automatically surfaces relevant past knowledge:
|
|
525
|
-
- File path pattern matching (editing `auth/*.ts` → security memories)
|
|
526
|
-
- Keyword detection (typing "database" → SQL pattern memories)
|
|
527
|
-
- Category association (bug-fix context → past fix patterns)
|
|
528
|
-
- Co-occurrence networks (memories activated together strengthen their link)
|
|
529
|
-
- Learned trigger patterns that improve with use
|
|
530
|
-
|
|
531
|
-
```bash
|
|
532
|
-
shadow-brain recall . --file src/auth/login.ts --keywords "jwt,session"
|
|
533
|
-
# → Activates 8 memories | Top: "JWT rotation pattern (92%)"
|
|
534
|
-
```
|
|
535
|
-
|
|
536
|
-
</td>
|
|
537
|
-
<td width="50%">
|
|
538
|
-
|
|
539
|
-
### Multi-Agent Intelligence Layer
|
|
540
|
-
|
|
541
|
-
**Consensus Engine** — voting, trust scoring, conflict resolution.
|
|
542
|
-
|
|
543
|
-
When multiple AI agents observe the same codebase, they may produce conflicting insights. This engine:
|
|
544
|
-
1. Collects proposals from agents
|
|
545
|
-
2. Opens voting windows (agree/disagree/abstain with confidence)
|
|
546
|
-
3. Computes trust-weighted agreement scores
|
|
547
|
-
4. Resolves conflicts via confidence intervals
|
|
548
|
-
5. Tracks long-term agent trust based on proposal accuracy
|
|
198
|
+
## 🚀 30-Second Quickstart
|
|
549
199
|
|
|
550
200
|
```bash
|
|
551
|
-
|
|
552
|
-
shadow-brain
|
|
553
|
-
shadow-brain consensus vote <id> agree 0.9 "Industry standard"
|
|
554
|
-
shadow-brain consensus results
|
|
555
|
-
```
|
|
201
|
+
# 1. Install
|
|
202
|
+
npx @theihtisham/agent-shadow-brain@latest attach-all
|
|
556
203
|
|
|
557
|
-
|
|
204
|
+
# 2. Launch the dashboard
|
|
205
|
+
shadow-brain dash .
|
|
206
|
+
# → open http://localhost:7341/
|
|
558
207
|
|
|
559
|
-
|
|
560
|
-
-
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
- Category-based organization (security, performance, architecture...)
|
|
564
|
-
- Trust scores for rule sources
|
|
208
|
+
# 3. Seed the brain (optional — populates example data)
|
|
209
|
+
shadow-brain reputation sign --agent claude-code --ver 4.7 --project demo \
|
|
210
|
+
--decision "use bcrypt cost 12 for all password hashing" \
|
|
211
|
+
--category security --confidence 0.92
|
|
565
212
|
|
|
566
|
-
|
|
567
|
-
shadow-brain collective status
|
|
568
|
-
shadow-brain collective propose "Always validate file upload MIME types" security
|
|
569
|
-
shadow-brain collective search performance
|
|
213
|
+
# 4. Every new AI agent session automatically gets context injected
|
|
570
214
|
```
|
|
571
215
|
|
|
572
|
-
|
|
573
|
-
</tr>
|
|
574
|
-
</table>
|
|
216
|
+
**That's it.** Open any project in Claude Code / Cursor / any supported agent — Shadow Brain is already running under the hood.
|
|
575
217
|
|
|
576
218
|
---
|
|
577
219
|
|
|
578
|
-
##
|
|
579
|
-
|
|
580
|
-
### 8 Breakthrough Modules (included in v5.1.1)
|
|
581
|
-
|
|
582
|
-
<table>
|
|
583
|
-
<tr>
|
|
584
|
-
<td width="50%">
|
|
585
|
-
|
|
586
|
-
### Quantum Memory Layer
|
|
587
|
-
|
|
588
|
-
**TurboQuant Infinite Memory** — never forget anything, ever.
|
|
589
|
-
|
|
590
|
-
Based on Google Research's **TurboQuant** (ICLR 2026):
|
|
591
|
-
- **PolarQuant**: 2 bits per dimension (polar coordinate quantization)
|
|
592
|
-
- **QJL Residual**: 1 bit per dimension (random rotation + sign)
|
|
593
|
-
- **Total**: 3 bits/dim = **6x compression** with <1% accuracy loss
|
|
594
|
-
- **Result**: Infinite retention — old knowledge is compressed, never deleted
|
|
595
|
-
|
|
596
|
-
```bash
|
|
597
|
-
shadow-brain turbo stats
|
|
598
|
-
shadow-brain turbo search "authentication patterns"
|
|
599
|
-
```
|
|
600
|
-
|
|
601
|
-
**SSSP Quantum Router** — deterministic shortest-path message routing.
|
|
602
|
-
|
|
603
|
-
Based on **"Breaking the Sorting Barrier"** (arXiv 2504.17033, Duan et al.):
|
|
604
|
-
- **BMSSP Algorithm**: O(m log<sup>2/3</sup> n) — breaks the sorting barrier
|
|
605
|
-
- **Deterministic**: No randomization, provably correct
|
|
606
|
-
|
|
607
|
-
```bash
|
|
608
|
-
shadow-brain route status
|
|
609
|
-
shadow-brain route find node-A node-B
|
|
610
|
-
```
|
|
611
|
-
|
|
612
|
-
</td>
|
|
613
|
-
<td width="50%">
|
|
614
|
-
|
|
615
|
-
### Self-Evolution Layer
|
|
616
|
-
|
|
617
|
-
**Genetic Algorithm Self-Evolution** — rules that write themselves.
|
|
618
|
-
|
|
619
|
-
- **Population**: 50 genetic rule chromosomes
|
|
620
|
-
- **Selection**: Tournament (k=5) — survival of the fittest
|
|
621
|
-
- **Crossover**: Single-point recombination
|
|
622
|
-
- **Mutation**: Gaussian noise (Box-Muller transform, sigma=0.1)
|
|
623
|
-
- **Fitness**: accuracy x coverage x (1 / falsePositiveRate)
|
|
624
|
-
|
|
625
|
-
```bash
|
|
626
|
-
shadow-brain evolve status
|
|
627
|
-
shadow-brain evolve run
|
|
628
|
-
shadow-brain evolve best-rules security
|
|
629
|
-
```
|
|
630
|
-
|
|
631
|
-
**Cross-Agent Intelligence Protocol (CAIP)** — agents that talk to each other.
|
|
632
|
-
|
|
633
|
-
Your Claude Code session learns what your Cursor session discovered:
|
|
634
|
-
- Zero-config broadcast protocol
|
|
635
|
-
- Agent identification + insight tagging
|
|
636
|
-
- Multi-agent consensus building
|
|
637
|
-
|
|
638
|
-
```bash
|
|
639
|
-
shadow-brain caip status
|
|
640
|
-
shadow-brain caip broadcast "Security pattern detected"
|
|
641
|
-
```
|
|
220
|
+
## 🧪 The Hive Mind Explainer (2 minutes)
|
|
642
221
|
|
|
643
|
-
|
|
644
|
-
</tr>
|
|
645
|
-
<tr>
|
|
646
|
-
<td width="50%">
|
|
222
|
+
[](https://github.com/theihtisham/agent-shadow-brain/raw/main/docs/launch/shadow-brain-motion-explainer-narrated.mp4)
|
|
647
223
|
|
|
648
|
-
|
|
224
|
+
**[▶ Click here to watch](https://github.com/theihtisham/agent-shadow-brain/raw/main/docs/launch/shadow-brain-motion-explainer-narrated.mp4)** · Full motion graphics explainer with voice-over walking through every feature, the live dashboard, and the 30-second install.
|
|
649
225
|
|
|
650
|
-
|
|
226
|
+
Local file: `docs/launch/shadow-brain-motion-explainer-narrated.mp4` (2:05 · 1080p · narrated).
|
|
651
227
|
|
|
652
|
-
|
|
653
|
-
- Evidence scoring with confidence thresholds
|
|
654
|
-
- Verdict: `real` | `hallucinated` | `uncertain`
|
|
655
|
-
|
|
656
|
-
```bash
|
|
657
|
-
shadow-brain defense status
|
|
658
|
-
shadow-brain defense scan "This API endpoint exists at /api/v2/users"
|
|
659
|
-
```
|
|
660
|
-
|
|
661
|
-
**Swarm Intelligence** — Ant Colony Optimization for file prioritization.
|
|
228
|
+
---
|
|
662
229
|
|
|
663
|
-
|
|
664
|
-
- Evaporation: decay over time to avoid staleness
|
|
230
|
+
## 📖 CLI Reference (top commands)
|
|
665
231
|
|
|
666
232
|
```bash
|
|
667
|
-
|
|
668
|
-
shadow-brain
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
|
|
233
|
+
# Attachment + lifecycle
|
|
234
|
+
shadow-brain attach-all # wire every detected agent
|
|
235
|
+
shadow-brain detach-all # remove every hook
|
|
236
|
+
shadow-brain audit-hooks # list what's installed
|
|
237
|
+
shadow-brain dash . # launch web dashboard at :7341
|
|
238
|
+
shadow-brain mcp # start MCP server at :7342
|
|
673
239
|
|
|
674
|
-
|
|
240
|
+
# v6 Hive Mind
|
|
241
|
+
shadow-brain hive status # cross-module status
|
|
242
|
+
shadow-brain subagent sliver --parent claude-code --task "refactor auth"
|
|
243
|
+
shadow-brain causal trace <id> # render ancestor DAG
|
|
244
|
+
shadow-brain dream run # trigger idle reflection now
|
|
245
|
+
shadow-brain debate "Redis or Postgres?" --context "10k users"
|
|
246
|
+
shadow-brain premortem "migrate auth to passkeys"
|
|
247
|
+
shadow-brain reputation sign --agent claude-code --ver 4.7 --project X \
|
|
248
|
+
--decision "..." --category security --confidence 0.92
|
|
249
|
+
shadow-brain reputation badge claude-code --ver 4.7
|
|
675
250
|
|
|
676
|
-
|
|
251
|
+
# Memory + analytics
|
|
252
|
+
shadow-brain global recall --keywords "auth"
|
|
253
|
+
shadow-brain tokens report # cross-agent spend + savings
|
|
254
|
+
shadow-brain forget consolidate # run sleep cycle
|
|
255
|
+
shadow-brain formal generate "always use parameterized SQL"
|
|
256
|
+
shadow-brain formal export-eslint
|
|
677
257
|
|
|
678
|
-
|
|
679
|
-
-
|
|
680
|
-
-
|
|
258
|
+
# Privacy + trust
|
|
259
|
+
shadow-brain airgap enable --policy strict
|
|
260
|
+
shadow-brain encrypt file ~/.shadow-brain/global.json --passphrase ...
|
|
261
|
+
shadow-brain quarantine list
|
|
681
262
|
|
|
682
|
-
|
|
683
|
-
shadow-brain
|
|
684
|
-
shadow-brain
|
|
685
|
-
shadow-brain graph cycles
|
|
686
|
-
```
|
|
263
|
+
# Sharing
|
|
264
|
+
shadow-brain exchange export --name "react-expert-v1" --tags react,auth
|
|
265
|
+
shadow-brain exchange import ~/brain-packs/react-expert-v1.json
|
|
687
266
|
|
|
688
|
-
|
|
689
|
-
|
|
690
|
-
- Bug risk scoring: `low` | `medium` | `high` | `critical`
|
|
691
|
-
- Technical debt forecasting
|
|
692
|
-
- Anomaly detection in change patterns
|
|
693
|
-
|
|
694
|
-
```bash
|
|
695
|
-
shadow-brain predict bugs .
|
|
267
|
+
# Full list
|
|
268
|
+
shadow-brain --help
|
|
696
269
|
```
|
|
697
270
|
|
|
698
|
-
</td>
|
|
699
|
-
</tr>
|
|
700
|
-
</table>
|
|
701
|
-
|
|
702
271
|
---
|
|
703
272
|
|
|
704
|
-
##
|
|
705
|
-
|
|
706
|
-
Shadow Brain v5.1.1 implements algorithms from **peer-reviewed research**:
|
|
707
|
-
|
|
708
|
-
| Algorithm | Paper / Origin | Application | Complexity |
|
|
709
|
-
|---|---|---|---|
|
|
710
|
-
| **Hierarchical Compression** | Novel 4-tier system | Infinite memory with drill-down | O(n) per tier |
|
|
711
|
-
| **Associative Recall** | Spreading activation model | Context-triggered memory activation | O(n x k) |
|
|
712
|
-
| **Consensus Protocol** | Byzantine fault tolerance | Multi-agent agreement with trust | O(v x log v) |
|
|
713
|
-
| **TurboQuant** | Google Research, ICLR 2026 | Vector compression (PolarQuant + QJL) | O(n) per vector |
|
|
714
|
-
| **BMSSP (SSSP)** | arXiv 2504.17033, Duan et al. | Neural mesh message routing | O(m log<sup>2/3</sup> n) |
|
|
715
|
-
| **Shannon Entropy** | Claude Shannon, 1948 | Cross-project insight relevance scoring | O(n) |
|
|
716
|
-
| **Bayesian Inference** | Thomas Bayes, 1763 | Confidence updating, meta-learning | O(1) per update |
|
|
717
|
-
| **Cosine Similarity** | Vector space model | Knowledge deduplication | O(d) per pair |
|
|
718
|
-
| **PageRank** | Brin & Page, 1998 | Code entity impact analysis | O(V + E) per iteration |
|
|
719
|
-
| **Tarjan's SCC** | Robert Tarjan, 1972 | Dependency cycle detection | O(V + E) |
|
|
720
|
-
| **Winnowing** | Schleimer et al., 2003 | Code duplicate fingerprinting | O(n) |
|
|
721
|
-
| **Box-Muller** | Box & Muller, 1958 | Gaussian mutation in genetic algorithm | O(1) per sample |
|
|
722
|
-
| **Ant Colony (ACO)** | Dorigo, 1992 | File priority pheromone system | O(n x m) |
|
|
723
|
-
| **Tournament Selection** | Goldberg, 1989 | Genetic rule selection (k=5) | O(k) per selection |
|
|
724
|
-
|
|
725
|
-
### TurboQuant Pipeline Detail
|
|
273
|
+
## 🎯 Tweetable Talking Points
|
|
726
274
|
|
|
727
|
-
|
|
728
|
-
Input Vector (64-dim, float64)
|
|
729
|
-
|
|
|
730
|
-
v
|
|
731
|
-
+-------------+
|
|
732
|
-
| PolarQuant |-- Cartesian -> Polar coordinates
|
|
733
|
-
| 2 bits/dim |-- Quantize angles to 4 levels (2 bits each)
|
|
734
|
-
+------+-------+ Pack into Uint8Array
|
|
735
|
-
|
|
|
736
|
-
v
|
|
737
|
-
+-------------+
|
|
738
|
-
| QJL Residual|-- Random rotation (Hadamard-like)
|
|
739
|
-
| 1 bit/dim |-- Sign extraction (1 bit per dim)
|
|
740
|
-
+------+-------+ Pack into Uint8Array
|
|
741
|
-
|
|
|
742
|
-
v
|
|
743
|
-
TurboVector { polar: Uint8Array, qjl: Uint8Array, dim: number, radius: number }
|
|
744
|
-
= 3 bits/dim total = 6x compression from float64
|
|
745
|
-
= ZERO FORGETTING -- compressed knowledge stays searchable forever
|
|
746
|
-
```
|
|
275
|
+
> *"Shadow Brain is the first open-source brain that works with sub-agents. Claude Task, Cursor Composer, CrewAI, LangGraph, AutoGen — all finally share context. One `npx` command. Zero API keys."*
|
|
747
276
|
|
|
748
|
-
|
|
749
|
-
|
|
750
|
-
## Features
|
|
751
|
-
|
|
752
|
-
<table>
|
|
753
|
-
<tr>
|
|
754
|
-
<td width="20%">
|
|
755
|
-
|
|
756
|
-
### Hyper-Cognitive (v5.1.1)
|
|
757
|
-
- Built-in LSP Server
|
|
758
|
-
- Custom LLM Fine-Tuning
|
|
759
|
-
- Smart Cache (3-tier)
|
|
760
|
-
- Intent Engine (NLP)
|
|
761
|
-
- Code DNA Fingerprinting
|
|
762
|
-
- Temporal Intelligence
|
|
763
|
-
|
|
764
|
-
</td>
|
|
765
|
-
<td width="20%">
|
|
766
|
-
|
|
767
|
-
### Zero Config (v5.0.1)
|
|
768
|
-
- Auto-detect project + tools
|
|
769
|
-
- MCP for ALL AI tools
|
|
770
|
-
- Rich web dashboard
|
|
771
|
-
- Natural language queries
|
|
772
|
-
- Plugin system
|
|
773
|
-
- Brain export/import
|
|
774
|
-
- Git hook auto-install
|
|
775
|
-
|
|
776
|
-
</td>
|
|
777
|
-
<td width="20%">
|
|
778
|
-
|
|
779
|
-
### Infinite Intelligence (v5)
|
|
780
|
-
- 4-tier hierarchical memory
|
|
781
|
-
- Context-triggered recall
|
|
782
|
-
- Multi-agent consensus
|
|
783
|
-
- Collective cross-project learning
|
|
784
|
-
|
|
785
|
-
</td>
|
|
786
|
-
<td width="20%">
|
|
787
|
-
|
|
788
|
-
### Hyper-Intelligence (v4)
|
|
789
|
-
- TurboQuant infinite memory
|
|
790
|
-
- SSSP quantum routing
|
|
791
|
-
- Self-evolving genetic rules
|
|
792
|
-
- Cross-agent protocol (CAIP)
|
|
793
|
-
- Adversarial defense
|
|
794
|
-
- Swarm intelligence (ACO)
|
|
795
|
-
- Knowledge Graph + PageRank
|
|
796
|
-
- Predictive bug forecasting
|
|
797
|
-
|
|
798
|
-
</td>
|
|
799
|
-
<td width="20%">
|
|
800
|
-
|
|
801
|
-
### Developer Experience
|
|
802
|
-
- **60+ CLI commands**
|
|
803
|
-
- MCP Server (19 tools)
|
|
804
|
-
- Built-in LSP Server
|
|
805
|
-
- Web dashboard (real-time)
|
|
806
|
-
- Terminal UI (Ink/React)
|
|
807
|
-
- Pre-commit hooks
|
|
808
|
-
- GitHub Actions CI
|
|
809
|
-
- Plugin architecture
|
|
810
|
-
|
|
811
|
-
</td>
|
|
812
|
-
</tr>
|
|
813
|
-
</table>
|
|
814
|
-
|
|
815
|
-
---
|
|
277
|
+
> *"Every AI decision Shadow Brain makes is Ed25519-signed. Every cause is traced. Every collision is caught before it happens. Free forever."*
|
|
816
278
|
|
|
817
|
-
|
|
818
|
-
|
|
819
|
-
### v5.1.1 Module Map (22 modules)
|
|
820
|
-
|
|
821
|
-
| Module | File | What It Does | Since |
|
|
822
|
-
|---|---|---|---|
|
|
823
|
-
| **LSP Server** | `brain/lsp-server.ts` | Built-in Language Server Protocol (stdio+TCP) | v5.1.1 |
|
|
824
|
-
| **Fine-Tuning Engine** | `brain/fine-tuning-engine.ts` | Custom LLM training data generation | v5.1.1 |
|
|
825
|
-
| **Smart Cache** | `brain/smart-cache.ts` | Multi-tier caching with predictive prefetch | v5.1.1 |
|
|
826
|
-
| **Intent Engine** | `brain/intent-engine.ts` | Natural language command understanding | v5.1.1 |
|
|
827
|
-
| **Code DNA** | `brain/code-dna.ts` | 9-gene code fingerprinting + similarity | v5.1.1 |
|
|
828
|
-
| **Temporal Intelligence** | `brain/temporal-intelligence.ts` | Velocity tracking, heatmaps, bug prediction | v5.1.1 |
|
|
829
|
-
| **Auto Setup** | `brain/auto-setup.ts` | Zero-config project + tool detection | v5.0.1 |
|
|
830
|
-
| **MCP Server** | `brain/mcp-server.ts` | 19-tool MCP server for all AI tools | v5.0.1 |
|
|
831
|
-
| **Plugin System** | `brain/plugin-system.ts` | Hookable analysis pipeline | v5.0.1 |
|
|
832
|
-
| **Brain Portability** | `brain/brain-portability.ts` | Export/import brain state | v5.0.1 |
|
|
833
|
-
| **Dashboard** | `dashboard/server.ts` | Real-time WebSocket dashboard | v5.0.1 |
|
|
834
|
-
| **Hierarchical Memory** | `brain/hierarchical-memory.ts` | 4-tier infinite memory | v5.0.0 |
|
|
835
|
-
| **Context Recall** | `brain/context-recall.ts` | Associative memory activation | v5.0.0 |
|
|
836
|
-
| **Consensus Engine** | `brain/consensus-engine.ts` | Multi-agent voting + trust | v5.0.0 |
|
|
837
|
-
| **Collective Learning** | `brain/collective-learning.ts` | Cross-project rule sharing | v5.0.0 |
|
|
838
|
-
| **TurboMemory** | `brain/turbo-memory.ts` | 6x compressed infinite memory | v4.0.0 |
|
|
839
|
-
| **SSSP Router** | `brain/sssp-router.ts` | Sub-sorting routing | v4.0.0 |
|
|
840
|
-
| **Self-Evolution** | `brain/self-evolution.ts` | Genetic rule optimization | v4.0.0 |
|
|
841
|
-
| **Cross-Agent** | `brain/cross-agent-protocol.ts` | Multi-agent broadcast | v4.0.0 |
|
|
842
|
-
| **Adversarial** | `brain/adversarial-defense.ts` | Hallucination detection | v4.0.0 |
|
|
843
|
-
| **Swarm** | `brain/swarm-intelligence.ts` | File priority pheromones | v4.0.0 |
|
|
844
|
-
| **Knowledge Graph** | `brain/knowledge-graph.ts` | PageRank impact analysis | v4.0.0 |
|
|
845
|
-
| **Predictive** | `brain/predictive-engine.ts` | Bug risk & debt forecasting | v4.0.0 |
|
|
279
|
+
> *"22 novel features nobody else has. Free. Open source. Local-first. `npx @theihtisham/agent-shadow-brain`."*
|
|
846
280
|
|
|
847
281
|
---
|
|
848
282
|
|
|
849
|
-
##
|
|
283
|
+
## 🛠️ For Contributors
|
|
850
284
|
|
|
851
|
-
|
|
852
|
-
|
|
853
|
-
|
|
854
|
-
|
|
855
|
-
|
|
856
|
-
|
|
857
|
-
|
|
858
|
-
| `shadow-brain health [dir]` | Health score (A-F grading) |
|
|
859
|
-
| `shadow-brain fix [dir]` | Smart fix suggestions |
|
|
860
|
-
| `shadow-brain report [dir]` | HTML/MD/JSON reports |
|
|
861
|
-
| `shadow-brain metrics [dir]` | Code metrics |
|
|
862
|
-
| `shadow-brain scan [dir]` | Vulnerability scanner |
|
|
863
|
-
| `shadow-brain pr [dir]` | Generate PR description |
|
|
864
|
-
| `shadow-brain commit-msg [dir]` | Generate commit message |
|
|
865
|
-
| `shadow-brain ci [dir]` | GitHub Actions workflow |
|
|
866
|
-
| `shadow-brain hook [dir]` | Pre-commit hook |
|
|
867
|
-
| `shadow-brain dash [dir]` | Web dashboard |
|
|
868
|
-
| `shadow-brain mcp` | MCP server mode |
|
|
869
|
-
| `shadow-brain inject <msg>` | Inject into agent memory |
|
|
870
|
-
| `shadow-brain status` | Current configuration |
|
|
871
|
-
| `shadow-brain setup` | Interactive setup wizard |
|
|
872
|
-
| `shadow-brain doctor` | Health check & diagnostics |
|
|
873
|
-
| `shadow-brain ask <question>` | Natural language brain query |
|
|
874
|
-
|
|
875
|
-
### v5.1.1 Hyper-Cognitive Commands (NEW)
|
|
876
|
-
|
|
877
|
-
| Command | Description |
|
|
878
|
-
|---|---|
|
|
879
|
-
| `shadow-brain lsp [--stdio\|--tcp PORT]` | Start built-in LSP server |
|
|
880
|
-
| `shadow-brain fine-tune status` | Fine-tuning training data stats |
|
|
881
|
-
| `shadow-brain fine-tune generate [dir]` | Generate training pairs from code |
|
|
882
|
-
| `shadow-brain fine-tune export [path]` | Export JSONL dataset for fine-tuning |
|
|
883
|
-
| `shadow-brain cache stats` | Smart cache hit rate, tier sizes, memory |
|
|
884
|
-
| `shadow-brain cache clear` | Clear all cache tiers |
|
|
885
|
-
| `shadow-brain intent <text>` | Parse natural language intent |
|
|
886
|
-
| `shadow-brain dna analyze [dir]` | Generate Code DNA profiles |
|
|
887
|
-
| `shadow-brain dna compare <f1> <f2>` | Compare two file fingerprints |
|
|
888
|
-
| `shadow-brain dna similar <file>` | Find structurally similar files |
|
|
889
|
-
| `shadow-brain temporal stats` | Velocity, anomalies, predictions |
|
|
890
|
-
| `shadow-brain temporal hot` | Top 10 hottest files by churn |
|
|
891
|
-
| `shadow-brain temporal predict` | Bug risk predictions |
|
|
892
|
-
| `shadow-brain temporal timeline` | Recent event timeline |
|
|
893
|
-
|
|
894
|
-
### v5.0.1 Commands
|
|
895
|
-
|
|
896
|
-
| Command | Description |
|
|
897
|
-
|---|---|
|
|
898
|
-
| `shadow-brain off` | Clean shutdown of all brain processes |
|
|
899
|
-
| `shadow-brain ask <question>` | Natural language query to the brain |
|
|
900
|
-
| `shadow-brain export [-o dir]` | Export full brain state to JSON |
|
|
901
|
-
| `shadow-brain import <file> [--merge]` | Import brain state |
|
|
902
|
-
| `shadow-brain plugin list` | List installed plugins |
|
|
903
|
-
| `shadow-brain plugin create <name>` | Create plugin from template |
|
|
904
|
-
| `shadow-brain plugin stats` | Plugin system statistics |
|
|
905
|
-
|
|
906
|
-
### v5.0.0 Infinite Intelligence Commands
|
|
285
|
+
```bash
|
|
286
|
+
git clone https://github.com/theihtisham/agent-shadow-brain.git
|
|
287
|
+
cd agent-shadow-brain
|
|
288
|
+
npm install
|
|
289
|
+
npm run build
|
|
290
|
+
npm test # 148/148 tests
|
|
291
|
+
npm run dev # ts-node dev mode
|
|
907
292
|
|
|
908
|
-
|
|
909
|
-
|
|
910
|
-
| `shadow-brain memory stats` | 4-tier hierarchical memory stats |
|
|
911
|
-
| `shadow-brain memory store <text>` | Store knowledge at raw tier |
|
|
912
|
-
| `shadow-brain memory search <query>` | Cross-tier semantic search |
|
|
913
|
-
| `shadow-brain recall . --file <f>` | Context-triggered associative recall |
|
|
914
|
-
| `shadow-brain consensus status` | Multi-agent consensus stats |
|
|
915
|
-
| `shadow-brain consensus propose <text> <cat> <conf>` | Submit proposal for voting |
|
|
916
|
-
| `shadow-brain consensus vote <id> <vote> <conf> <reason>` | Vote on a proposal |
|
|
917
|
-
| `shadow-brain consensus results` | All resolved proposals |
|
|
918
|
-
| `shadow-brain collective status` | Cross-project rule stats |
|
|
919
|
-
| `shadow-brain collective propose <text> <cat>` | Propose a collective rule |
|
|
920
|
-
| `shadow-brain collective search <cat>` | Search collective rules by category |
|
|
921
|
-
| `shadow-brain v5 [dir]` | Run ALL v5.0.0 analyses |
|
|
922
|
-
|
|
923
|
-
### v4.0.0 Hyper-Intelligence Commands
|
|
924
|
-
|
|
925
|
-
| Command | Description |
|
|
926
|
-
|---|---|
|
|
927
|
-
| `shadow-brain turbo stats` | TurboQuant infinite memory stats |
|
|
928
|
-
| `shadow-brain turbo search <q>` | Semantic search compressed memory |
|
|
929
|
-
| `shadow-brain route status` | SSSP routing status |
|
|
930
|
-
| `shadow-brain route find <from> <to>` | Shortest path query |
|
|
931
|
-
| `shadow-brain caip status` | Cross-agent protocol status |
|
|
932
|
-
| `shadow-brain caip broadcast <msg>` | Broadcast to all agents |
|
|
933
|
-
| `shadow-brain evolve status` | Genetic algorithm generation stats |
|
|
934
|
-
| `shadow-brain evolve run` | Trigger evolution cycle |
|
|
935
|
-
| `shadow-brain evolve best-rules [cat]` | Top evolved rules by category |
|
|
936
|
-
| `shadow-brain predict bugs [dir]` | Bug risk prediction |
|
|
937
|
-
| `shadow-brain graph build [dir]` | Build knowledge graph + PageRank |
|
|
938
|
-
| `shadow-brain swarm status` | Swarm convergence + priorities |
|
|
939
|
-
| `shadow-brain swarm priorities` | File hotspot ranking |
|
|
940
|
-
| `shadow-brain defense status` | Adversarial defense statistics |
|
|
941
|
-
| `shadow-brain defense scan <text>` | Scan text for hallucination patterns |
|
|
942
|
-
| `shadow-brain v4 [dir]` | Run ALL v4.0.0 analyses |
|
|
293
|
+
# Rebuild the explainer video
|
|
294
|
+
node tools/record-motion-explainer.mjs
|
|
943
295
|
|
|
944
|
-
|
|
296
|
+
# Capture fresh dashboard screenshots
|
|
297
|
+
node tools/capture-screenshots.mjs
|
|
945
298
|
|
|
946
|
-
|
|
947
|
-
|
|
948
|
-
```typescript
|
|
949
|
-
import {
|
|
950
|
-
Orchestrator,
|
|
951
|
-
// v5.1.1 — Hyper-Cognitive modules
|
|
952
|
-
LSPServer,
|
|
953
|
-
FineTuningEngine,
|
|
954
|
-
SmartCache,
|
|
955
|
-
IntentEngine,
|
|
956
|
-
CodeDNA,
|
|
957
|
-
TemporalIntelligence,
|
|
958
|
-
// v5.0.1 — Zero-Config modules
|
|
959
|
-
AutoSetup,
|
|
960
|
-
PluginSystem,
|
|
961
|
-
BrainPortability,
|
|
962
|
-
// v5.0.0 — Infinite Intelligence modules
|
|
963
|
-
HierarchicalMemory,
|
|
964
|
-
ContextRecall,
|
|
965
|
-
ConsensusEngine,
|
|
966
|
-
CollectiveLearning,
|
|
967
|
-
// v4.0.0 — Hyper-Intelligence modules
|
|
968
|
-
TurboMemory,
|
|
969
|
-
SSSPRouter,
|
|
970
|
-
SelfEvolution,
|
|
971
|
-
CrossAgentProtocol,
|
|
972
|
-
AdversarialDefense,
|
|
973
|
-
SwarmIntelligence,
|
|
974
|
-
KnowledgeGraph,
|
|
975
|
-
PredictiveEngine,
|
|
976
|
-
NeuralMesh,
|
|
977
|
-
} from '@theihtisham/agent-shadow-brain';
|
|
978
|
-
|
|
979
|
-
// v5.1.1 — Built-in LSP server
|
|
980
|
-
const lsp = new LSPServer('./my-project');
|
|
981
|
-
lsp.start({ mode: 'tcp', port: 2087 }); // or { mode: 'stdio' }
|
|
982
|
-
|
|
983
|
-
// v5.1.1 — Smart Cache
|
|
984
|
-
const cache = new SmartCache({ maxHotEntries: 200, enablePrefetch: true });
|
|
985
|
-
cache.set('analysis:auth', analysisResult, { ttl: 300_000, tags: ['security'] });
|
|
986
|
-
const cached = cache.get('analysis:auth');
|
|
987
|
-
|
|
988
|
-
// v5.1.1 — Temporal Intelligence
|
|
989
|
-
const temporal = new TemporalIntelligence('./my-project');
|
|
990
|
-
temporal.recordCommit(['src/auth.ts'], 'fix: JWT rotation');
|
|
991
|
-
const velocity = temporal.getVelocity(); // { daily, weekly, trend: 'accelerating' }
|
|
992
|
-
const bugRisks = temporal.predictBugs(10);
|
|
993
|
-
|
|
994
|
-
// v5.1.1 — Code DNA
|
|
995
|
-
const dna = new CodeDNA('./my-project');
|
|
996
|
-
const profile = await dna.analyze('src/auth.ts');
|
|
997
|
-
const similar = await dna.findSimilar('src/auth.ts', 5);
|
|
998
|
-
|
|
999
|
-
// v5.0.1 — Zero-config auto-setup
|
|
1000
|
-
const setup = new AutoSetup('./my-project');
|
|
1001
|
-
const config = await setup.detect();
|
|
1002
|
-
// → { projectType: 'fullstack', languages: ['typescript','python'], frameworks: ['next.js'], aiTools: [...] }
|
|
1003
|
-
await setup.installMCPForTools(['Claude Code', 'Cursor']);
|
|
1004
|
-
await setup.installGitHooks();
|
|
1005
|
-
|
|
1006
|
-
// Create the brain
|
|
1007
|
-
const brain = new Orchestrator({
|
|
1008
|
-
provider: 'anthropic',
|
|
1009
|
-
projectDir: './my-project',
|
|
1010
|
-
agents: ['claude-code', 'cursor', 'cline'],
|
|
1011
|
-
watchMode: true,
|
|
1012
|
-
autoInject: true,
|
|
1013
|
-
brainPersonality: 'balanced',
|
|
1014
|
-
});
|
|
1015
|
-
|
|
1016
|
-
// v5.0.1 — Plugin system
|
|
1017
|
-
const plugins = new PluginSystem('./my-project');
|
|
1018
|
-
await plugins.loadAll();
|
|
1019
|
-
await plugins.preAnalysis({ files: ['src/auth.ts'], projectDir: './my-project' });
|
|
1020
|
-
|
|
1021
|
-
// v5.0.1 — Brain portability
|
|
1022
|
-
const porter = new BrainPortability('./my-project');
|
|
1023
|
-
const { filePath, sizeBytes, checksum } = await porter.exportBrain();
|
|
1024
|
-
|
|
1025
|
-
// v5.0.0 — Infinite Intelligence
|
|
1026
|
-
const hmem = new HierarchicalMemory();
|
|
1027
|
-
await hmem.store('JWT rotation pattern: rotate every 24h with refresh tokens', 'security', 0.9);
|
|
1028
|
-
const results = hmem.search('jwt');
|
|
1029
|
-
|
|
1030
|
-
const recall = new ContextRecall(hmem);
|
|
1031
|
-
const activated = recall.recall({
|
|
1032
|
-
currentFile: 'src/auth/login.ts',
|
|
1033
|
-
currentCategory: 'security',
|
|
1034
|
-
recentEdits: ['src/auth/login.ts', 'src/middleware/auth.ts'],
|
|
1035
|
-
projectType: 'node',
|
|
1036
|
-
keywords: ['jwt', 'authentication', 'session'],
|
|
1037
|
-
});
|
|
1038
|
-
|
|
1039
|
-
const consensus = new ConsensusEngine('my-agent');
|
|
1040
|
-
const proposalId = consensus.propose('Use bcrypt cost factor 12', 'security', 0.95);
|
|
1041
|
-
|
|
1042
|
-
// Start everything
|
|
1043
|
-
await brain.start();
|
|
299
|
+
# Seed the brain with demo data
|
|
300
|
+
node tools/seed-brain.mjs
|
|
1044
301
|
```
|
|
1045
302
|
|
|
1046
|
-
|
|
1047
|
-
|
|
1048
|
-
## Health Score System
|
|
1049
|
-
|
|
1050
|
-
| Dimension | Weight | Checks |
|
|
1051
|
-
|---|---|---|
|
|
1052
|
-
| Security | 25% | Vulnerabilities, secrets, exposed keys |
|
|
1053
|
-
| Quality | 25% | Code smells, anti-patterns, complexity |
|
|
1054
|
-
| Performance | 15% | N+1 queries, memory leaks, blocking ops |
|
|
1055
|
-
| Architecture | 15% | Coupling, cohesion, dependencies |
|
|
1056
|
-
| Maintainability | 10% | Duplication, file sizes, comments |
|
|
1057
|
-
| Test Coverage | 10% | Test presence, assertion quality |
|
|
303
|
+
Issues, PRs, discussions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
1058
304
|
|
|
1059
305
|
---
|
|
1060
306
|
|
|
1061
|
-
##
|
|
307
|
+
## 📚 Documentation
|
|
1062
308
|
|
|
1063
|
-
|
|
1064
|
-
|
|
1065
|
-
|
|
1066
|
-
|
|
1067
|
-
|
|
1068
|
-
|
|
1069
|
-
| **[v5.1.1](docs/versions/v5.1.1.md)** | Hyper-Cognitive | 2026-04-18 | LSP Server, Fine-Tuning Engine, Smart Cache, Intent Engine, Code DNA, Temporal Intelligence |
|
|
1070
|
-
| **[v5.0.1](docs/versions/v5.0.1.md)** | Zero-Config | 2026-04-15 | Auto-Setup, MCP Server (19 tools), Dashboard, NLP Queries, Plugin System |
|
|
1071
|
-
| **[v5.0.0](docs/versions/v5.0.0.md)** | Infinite Intelligence | 2026-04-12 | Hierarchical Memory, Associative Recall, Multi-Agent Consensus, Collective Learning |
|
|
1072
|
-
| **[v4.0.0](docs/versions/v4.0.0.md)** | Hyper-Intelligence | 2026-04-08 | TurboQuant, SSSP Routing, Self-Evolution, CAIP, Adversarial Defense, Swarm, Knowledge Graph |
|
|
1073
|
-
| **[v3.0.0](docs/versions/v3.0.0.md)** | Hyper-Intelligence | 2026-04-01 | Cognitive Load Analysis, Security Audit Engine, Influence Map |
|
|
1074
|
-
| **[v2.1.0](docs/versions/v2.1.0.md)** | Quantum Neural Mesh | 2026-03-25 | Shannon Entropy, Cosine Similarity, Bayesian Confidence |
|
|
1075
|
-
| **[v2.0.0](docs/versions/v2.0.0.md)** | Super-Intelligence | 2026-03-18 | Semantic Analyzer, Dependency Graph, Code Similarity, MCP Server |
|
|
1076
|
-
| **[v1.0.0](docs/versions/v1.0.0.md)** | Foundation | 2026-02-28 | 7 Agent Adapters, Health Scoring, Smart Fixes, Vulnerability Scanning |
|
|
309
|
+
- **[CHANGELOG.md](CHANGELOG.md)** — release notes
|
|
310
|
+
- **[docs/versions/v6.0.0.md](docs/versions/v6.0.0.md)** — v6 release details
|
|
311
|
+
- **[docs/launch/HIVEMIND_VIDEO.md](docs/launch/HIVEMIND_VIDEO.md)** — video production pipeline
|
|
312
|
+
- **[docs/launch/screenshots/](docs/launch/screenshots/)** — all 29 dashboard screenshots
|
|
313
|
+
- **[SECURITY.md](SECURITY.md)** — security policy
|
|
314
|
+
- **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)** — community guidelines
|
|
1077
315
|
|
|
1078
316
|
---
|
|
1079
317
|
|
|
1080
|
-
##
|
|
1081
|
-
|
|
1082
|
-
| Agent | Status | MCP Support | Injection Target |
|
|
1083
|
-
|---|---|---|---|
|
|
1084
|
-
| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | Full Support | Auto-install | `CLAUDE.md`, `.claude/` |
|
|
1085
|
-
| [Cursor](https://cursor.sh/) | Full Support | Auto-install | `.cursor/mcp.json` |
|
|
1086
|
-
| [Kilo Code](https://kilocode.ai/) | Full Support | Auto-install | `.kilocode/rules.md` |
|
|
1087
|
-
| [Cline](https://github.com/cline/cline) | Full Support | Auto-install | `.clinerules` |
|
|
1088
|
-
| [OpenCode](https://github.com/opencode-ai/opencode) | Full Support | Yes | `AGENT.md` |
|
|
1089
|
-
| [Codex](https://github.com/openai/codex) | Full Support | Yes | `AGENTS.md` |
|
|
1090
|
-
| [Roo Code](https://roocode.com/) | Full Support | Yes | `.roo/rules.md` |
|
|
1091
|
-
| [Aider](https://aider.chat/) | Full Support | Yes | `.aider.conf.yml` |
|
|
1092
|
-
| [Windsurf](https://codeium.com/windsurf) | Detection | Yes | `.windsurfrules` |
|
|
318
|
+
## 💬 Community
|
|
1093
319
|
|
|
1094
|
-
|
|
320
|
+
- **[GitHub Issues](https://github.com/theihtisham/agent-shadow-brain/issues)** — bug reports, feature requests
|
|
321
|
+
- **[GitHub Discussions](https://github.com/theihtisham/agent-shadow-brain/discussions)** — questions, ideas, show-and-tell
|
|
322
|
+
- **[GitHub Releases](https://github.com/theihtisham/agent-shadow-brain/releases)** — download the explainer MP4 + release assets
|
|
1095
323
|
|
|
1096
|
-
|
|
1097
|
-
|
|
1098
|
-
```bash
|
|
1099
|
-
git clone https://github.com/theihtisham/agent-shadow-brain.git
|
|
1100
|
-
cd agent-shadow-brain
|
|
1101
|
-
npm install
|
|
1102
|
-
npm run build
|
|
1103
|
-
npm test
|
|
1104
|
-
```
|
|
324
|
+
**If Shadow Brain makes your AI agents smarter, star the repo ⭐**
|
|
1105
325
|
|
|
1106
326
|
---
|
|
1107
327
|
|
|
1108
|
-
##
|
|
1109
|
-
|
|
1110
|
-
- [x] ~~MCP Server, multi-project, team mode~~ (v2.0)
|
|
1111
|
-
- [x] ~~Cross-session neural mesh~~ (v2.1)
|
|
1112
|
-
- [x] ~~TurboQuant infinite memory~~ (v4.0)
|
|
1113
|
-
- [x] ~~SSSP quantum routing~~ (v4.0)
|
|
1114
|
-
- [x] ~~Self-evolving rules~~ (v4.0)
|
|
1115
|
-
- [x] ~~Cross-agent protocol~~ (v4.0)
|
|
1116
|
-
- [x] ~~Adversarial hallucination defense~~ (v4.0)
|
|
1117
|
-
- [x] ~~Hierarchical memory compression~~ (v5.0)
|
|
1118
|
-
- [x] ~~Context-triggered associative recall~~ (v5.0)
|
|
1119
|
-
- [x] ~~Multi-agent consensus protocol~~ (v5.0)
|
|
1120
|
-
- [x] ~~Collective cross-project learning~~ (v5.0)
|
|
1121
|
-
- [x] ~~Zero-config auto-setup~~ (v5.0.1)
|
|
1122
|
-
- [x] ~~MCP server for Cursor + all tools~~ (v5.0.1)
|
|
1123
|
-
- [x] ~~Rich web dashboard with real-time WebSocket~~ (v5.0.1)
|
|
1124
|
-
- [x] ~~Plugin system + brain export/import~~ (v5.0.1)
|
|
1125
|
-
- [x] ~~Custom LLM fine-tuning~~ (v5.1.1)
|
|
1126
|
-
- [x] ~~Language server (LSP)~~ (v5.1.1)
|
|
1127
|
-
- [x] ~~Web dashboard v3~~ (v5.1.1)
|
|
1128
|
-
- [ ] **Visual Studio Code integration** — inline insight overlays
|
|
1129
|
-
- [ ] **Multi-model orchestration** — route insights through multiple LLMs
|
|
1130
|
-
- [ ] **Real-time collaboration** — team brain with live cursors
|
|
328
|
+
## ⭐ Stargazers Over Time
|
|
1131
329
|
|
|
1132
|
-
|
|
1133
|
-
|
|
1134
|
-
## License
|
|
1135
|
-
|
|
1136
|
-
MIT License — see [LICENSE](LICENSE) for details.
|
|
330
|
+
[](https://star-history.com/#theihtisham/agent-shadow-brain&Date)
|
|
1137
331
|
|
|
1138
332
|
---
|
|
1139
333
|
|
|
1140
|
-
##
|
|
334
|
+
## 📜 License
|
|
1141
335
|
|
|
1142
|
-
**
|
|
336
|
+
**MIT** — see [LICENSE](LICENSE).
|
|
1143
337
|
|
|
1144
|
-
|
|
1145
|
-
[](https://www.npmjs.com/~theihtisham)
|
|
338
|
+
Free to use, modify, fork, commercialize. Local-first by default. Works offline, in air-gapped environments, in privacy-constrained enterprises. No telemetry. No phone-home. No trial expiration.
|
|
1146
339
|
|
|
1147
340
|
---
|
|
1148
341
|
|
|
1149
342
|
<div align="center">
|
|
1150
343
|
|
|
1151
|
-
###
|
|
344
|
+
### Built by [@theihtisham](https://github.com/theihtisham)
|
|
1152
345
|
|
|
1153
|
-
|
|
346
|
+
<a href="https://github.com/theihtisham"><img src="https://img.shields.io/badge/GitHub-theihtisham-181717?style=for-the-badge&logo=github" alt="GitHub"></a>
|
|
347
|
+
<a href="https://www.npmjs.com/~theihtisham"><img src="https://img.shields.io/badge/npm-@theihtisham-CB3837?style=for-the-badge&logo=npm" alt="npm"></a>
|
|
348
|
+
|
|
349
|
+
### The Hive Mind for every AI coding agent on your machine.
|
|
1154
350
|
|
|
1155
|
-
|
|
351
|
+
**`npx @theihtisham/agent-shadow-brain@latest attach-all`**
|
|
1156
352
|
|
|
1157
|
-
|
|
353
|
+
<sub>Topics: `ai` · `llm` · `claude-code` · `cursor` · `cline` · `codex` · `copilot` · `hive-mind` · `sub-agent` · `sabb` · `causal-chains` · `dream-engine` · `reputation-ledger` · `swarm-debate` · `pre-mortem` · `branch-brain` · `attention-heatmap` · `token-economy` · `forgetting-curve` · `formal-verification` · `calibration-monitor` · `air-gap` · `e2e-encryption` · `hallucination-quarantine` · `voice-mode` · `brain-garden` · `pr-review` · `team-brain` · `brain-exchange` · `local-first` · `ollama` · `anthropic` · `openai` · `openrouter` · `gemini` · `deepseek` · `moonshot` · `mistral` · `mcp-server` · `model-context-protocol` · `lsp-server` · `cross-agent` · `multi-agent` · `autonomous-agents` · `agentic-ai` · `vibe-coding` · `cursor-ai` · `developer-tools` · `developer-productivity` · `coding-assistant` · `ai-coding` · `code-review` · `static-analysis` · `knowledge-graph` · `semantic-search` · `vector-embeddings` · `prompt-caching` · `json-mode` · `chat-with-memory` · `ed25519` · `chacha20-poly1305` · `sssp` · `turboquant` · `iclr-2026` · `arxiv` · `zero-config` · `typescript` · `open-source` · `free-forever` · `mit-license`</sub>
|
|
1158
354
|
|
|
1159
355
|
</div>
|