@theihtisham/agent-shadow-brain 6.0.2 → 6.2.0

package/README.md

@@ -1,455 +1,427 @@
-<div align="center">
-
-<a href="https://github.com/theihtisham/agent-shadow-brain">
-  <img src="banner-v6.0.2.png" alt="Shadow Brain v6.0.2 — Singularity · 35 new modules · 5 viral features · 10 brain-quality upgrades · One brain, every agent" width="100%">
-</a>
-<a href="https://trendshift.io/repositories/25944" target="_blank"><img src="https://trendshift.io/api/badge/repositories/25944" alt="lsdefine%2FGenericAgent | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
-<br/><br/>
-
-<!-- v6.0.2 hero video — auto-plays muted on GitHub README -->
-<video src="https://raw.githubusercontent.com/theihtisham/agent-shadow-brain/main/docs/launch/shadow-brain-v6.0.2-hero.mp4"
-       poster="banner-v6.0.2.png"
-       autoplay
-       muted
-       loop
-       controls
-       playsinline
-       width="100%">
-  Your browser doesn't support inline video.
-  <a href="https://github.com/theihtisham/agent-shadow-brain/releases/tag/v6.0.2">Watch the v6.0.2 hero video on the release page</a>.
-</video>
-
-### 🎬 **2-minute v6.0.2 hero above — auto-plays muted · click 🔊 to unmute · [v6.0.2 release page](https://github.com/theihtisham/agent-shadow-brain/releases/tag/v6.0.2) · [original 2-min explainer](docs/launch/shadow-brain-motion-explainer-narrated.mp4) · [dashboard tour](docs/launch/shadow-brain-dashboard-tour.mp4)**
-
-[![npm version](https://img.shields.io/npm/v/@theihtisham/agent-shadow-brain?color=a855f7&labelColor=1a0a2e&style=for-the-badge&logo=npm)](https://www.npmjs.com/package/@theihtisham/agent-shadow-brain)
-[![npm downloads](https://img.shields.io/npm/dt/@theihtisham/agent-shadow-brain?color=06b6d4&labelColor=1a0a2e&style=for-the-badge)](https://www.npmjs.com/package/@theihtisham/agent-shadow-brain)
-[![GitHub stars](https://img.shields.io/github/stars/theihtisham/agent-shadow-brain?color=f59e0b&labelColor=1a0a2e&style=for-the-badge&logo=github)](https://github.com/theihtisham/agent-shadow-brain/stargazers)
-[![license](https://img.shields.io/badge/license-MIT-8b5cf6?labelColor=1a0a2e&style=for-the-badge)](https://github.com/theihtisham/agent-shadow-brain/blob/main/LICENSE)
-[![TypeScript](https://img.shields.io/badge/TypeScript-100%25-3178c6?labelColor=1a0a2e&style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
-[![node](https://img.shields.io/badge/node-%3E%3D18-22c55e?labelColor=1a0a2e&style=for-the-badge&logo=node.js)](https://nodejs.org/)
-[![Brain Modules](https://img.shields.io/badge/brain_modules-122-ec4899?labelColor=1a0a2e&style=for-the-badge)](#-architecture)
-[![CLI Commands](https://img.shields.io/badge/CLI-120%2B_commands-eab308?labelColor=1a0a2e&style=for-the-badge&logo=windowsterminal)](#-cli-reference)
-[![MCP Tools](https://img.shields.io/badge/MCP-60%2B_tools-8b5cf6?labelColor=1a0a2e&style=for-the-badge&logo=anthropic)](#-mcp-tools)
-[![Tests](https://img.shields.io/badge/tests-148%2F148_passing-10b981?labelColor=1a0a2e&style=for-the-badge&logo=vitest)](#)
-[![Local First](https://img.shields.io/badge/local--first-ollama_default-f97316?labelColor=1a0a2e&style=for-the-badge&logo=ollama)](#)
-[![Free](https://img.shields.io/badge/price-%240_forever-22c55e?labelColor=1a0a2e&style=for-the-badge)](#)
-
-<br/>
-
-# 🧠 Shadow Brain v6.0.2 — Singularity
-
-### *The first open-source brain that every AI coding agent on your machine can share.*
-
-**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.
-
-> **🆕 v6.0.2 "Singularity" — 19 world-first features. Every one of them shareable.**
->
-> **The 5 viral artifacts** — each renders as a tweet-ready PNG/SVG/MP4:
-> 🎬 **Brain Replay** · 🧬 **Brain DNA** · 🗳️ **Hive Voice** · ⏰ **Time Capsule** · 🔬 **Brain Diff**
->
-> **The 14 advanced features** — Spotify-Wrapped-meets-AI-codebase:
-> 🎵 **Brain Cinema** (auto 60s SVG-animated video of brain growth) · 🎼 **Brain Sonification** (your codebase as music) · 🏆 **Brain Trophies** (25 achievements + share cards) · 🎁 **Brain Holiday Card** (year-in-review) · 🧭 **Brain Coach** (proactive idle suggestions) · 🗺️ **Brain Quest** (gamified onboarding adventures) · 📓 **Brain Notebook** (Jupyter-style brain explorer) · ⚡ **Brain Reflex** (local-model inline completion) · 🔥 **Brain Roast** (comedy code reviews, 6 personas) · 🔮 **Brain Tarot** (78-card divination from git+brain) · 🎨 **Brain ASCII** (terminal art representations) · 😂 **Brain Memes** (auto-generated dev memes) · 🌌 **Brain 3D** (Three.js rotatable graph viewer) · 💞 **Brain Doppelganger** (find your codebase's twin)
->
-> **The infrastructure** — real ANN HNSW index · Constitution layer · Confidence Gate · multimodal vision (llava) · LoRA distillation pipeline · SWE-Bench-Lite eval harness · OpenTelemetry-lite tracing · git-trackable Markdown brain export/import.
->
-> [Full release notes →](docs/launch/RELEASE_NOTES_v6.0.2.md)
+# Agent Shadow Brain
+
+Local-first memory and coordination for AI coding agents.
+
+Version: 6.2.0
+
+<p align="center">
+  <img src="docs/launch/agent-shadow-brain-v6.0.3-banner.png" alt="Agent Shadow Brain shared local memory layer for AI agents" width="100%">
+</p>
+<p align="center">
+  <a href="https://trendshift.io/repositories/20881" target="_blank"><img src="https://trendshift.io/api/badge/repositories/20881" alt="chopratejas%2Fheadroom | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
+</p>
+<p align="center">
+  <img src="docs/launch/github-trending-ready.svg" alt="GitHub Trending Ready - Agent Shadow Brain v6.0.3 live on npm" width="420">
+</p>
+
+Agent Shadow Brain gives tools like Codex, Claude Code, Cursor, Cline, OpenCode, Aider, and related MCP clients a shared local memory layer. It stores compact, source-backed lessons about projects, recalls them later, generates fresh-session briefings, audits memory quality, and exports JSONL training/eval packs.
+
+It does not change model weights by itself. It helps agents work better by giving them relevant, current, source-linked context before and during complex work.
+
+## What's New in 6.2.0
+
+A major dashboard upgrade focused on clarity and visibility.
+
+- **Simple by default, Advanced on demand.** The dashboard opens with eight plain-English tabs (Home, Brain Map, Memories, Ask the Brain, Activity, Connected Tools, Brain Health, Settings). Flip to Advanced to reveal every feature — nothing was removed, just tidied.
+- **Brain Map.** An interactive graph of everything the brain remembers — memories, projects, tools, and tags — sized by importance (PageRank) and linked by shared context. Zoom, pan, click a node for details, and watch it grow live as new memories arrive.
+- **Realtime activity.** Memory writes, reflections, and tool events stream live over WebSocket instead of polling, with a live pulse on Home.
+- **Live Network.** A refreshed animation of your tools talking to the brain, with flowing signal pulses.
+- **Two-way knowledge seeding.** Quick-Save captures knowledge in one click; "Hand to Agent" generates a ready briefing to pass context back to any tool.
+- **Plain-language everywhere.** Cryptic feature names rewritten (e.g. Calibration → Accuracy, Pre-Mortem → Risk Check, Tokens → Cost & Usage), each with a hover description.
+
+<p align="center">
+  <img src="docs/screenshots/01-home.png" alt="Shadow Brain dashboard Home — summary of memories, connected tools, and live activity" width="100%">
+</p>
+<p align="center">
+  <img src="docs/screenshots/02-brain-map.png" alt="Brain Map — interactive memory constellation graph" width="100%">
+</p>
+<p align="center">
+  <img src="docs/screenshots/03-live-network.png" alt="Live Network — animated view of tools communicating with the brain" width="100%">
+</p>
+
+## What It Actually Does
+
+- Stores cross-project and cross-agent memories in a local JSON brain at `~/.shadow-brain/global.json`.
+- Recalls memories by project, agent, category, and keywords.
+- Generates source-backed resume packs for fresh sessions, account switches, context compaction, and handoffs.
+- Audits memory quality: source coverage, stale entries, duplicates, low-quality notes, recall health.
+- Creates verified memory seed drafts from dashboard/API, then requires user, agent, or dual approval before writing to durable memory.
+- Exports JSONL rows for evals, distillation, or local fine-tuning pipelines.
+- Provides CLI, dashboard API, and MCP tool surfaces.
+- Includes safety helpers such as hook audit, detach, and action firewall checks.
+- Works without telemetry and without an API key for local memory features.
+
+## What It Does Not Claim
+
+- It does not secretly train GPT, Claude, Gemini, or any remote model.
+- It does not guarantee perfect recall.
+- It does not replace project docs, tests, source control, or human review.
+- It does not make every listed agent automatically available. Agent support depends on local installation and hook/config compatibility.
+- It does not publish or sync data unless you explicitly use export, sync, or other sharing commands.
+
+## Install
 
 ```bash
-# 30 seconds. Every agent + sub-agent on your machine becomes smarter.
-npx @theihtisham/agent-shadow-brain@latest attach-all
+npm install -g @theihtisham/agent-shadow-brain
+```
+
+CLI binaries:
 
-# Or — the 30-second wow tour
-npx @theihtisham/agent-shadow-brain@latest demo
+```bash
+shadow-brain --help
+asb --help
 ```
 
-**[🎬 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)**
+You can also run without global install:
 
-</div>
+```bash
+npx @theihtisham/agent-shadow-brain@latest --help
+```
 
----
+## Safe First Run
 
-## ⚡ Install in 30 seconds
+Start by auditing before attaching hooks:
 
 ```bash
-# Method 1 — one command, every agent wired, dashboard launches
-npx @theihtisham/agent-shadow-brain@latest attach-all
+shadow-brain audit-hooks .
+shadow-brain live-brain status .
+```
 
-# Method 2 — global install
-npm install -g @theihtisham/agent-shadow-brain
-shadow-brain attach-all
-shadow-brain dash .                 # → http://localhost:7341/
+Only attach after you review what will be changed:
 
-# Method 3 — in a specific project only
-cd my-project
-npx @theihtisham/agent-shadow-brain attach-all
+```bash
+shadow-brain attach-all .
 ```
 
-**Zero config. Zero API key required. 100 % local-first.**
+Detach later if needed:
 
----
+```bash
+shadow-brain detach-all .
+```
 
-## 🆕 What's New in v6.0.2 — "Singularity"
+## v6.0.3: Live Brain
 
-> **35 new modules + 27 new CLI commands + 7 sample artifacts. Zero new npm deps. tsc-clean.**
+The 6.0.3 release focuses on practical long-memory improvement for agents.
 
-### 🌟 The 5 World-First Viral Features
+### Live Brain Status
 
-Every one of these renders as a tweet-ready PNG/SVG. *Cursor doesn't have these. Cline doesn't have these. Nobody has these.*
+```bash
+shadow-brain live-brain status .
+```
+
+Shows:
+
+- memory count
+- average memory quality
+- source coverage
+- stale memories
+- duplicate clusters
+- recall eval score
+- recommended cleanup actions
 
-| | Feature | What it does |
-|---|---|---|
-| 🎬 | **[Brain Replay](docs/launch/v6.0.2-samples/brain-replay-sample.svg)** | Scrubbable timeline of every brain event since day-zero. Drag the cursor, rewind to any moment. SVG export. |
-| 🧬 | **[Brain DNA](docs/launch/v6.0.2-samples/brain-dna-sample.svg)** | Spotify-Wrapped-style fingerprint card. 8 personality archetypes (The Architect, The Debugger, …). 1080×1080 share card. |
-| 🗳️ | **Hive Voice** | 3 local models debate-vote on every architecture question. See consensus, dissent, and confidence — live. SVG bar chart. |
-| ⏰ | **Brain Time Capsule** | Freeze + label + resurrect brain snapshots. "Here's what we knew about React in January." Ed25519-signed bundles. |
-| 🔬 | **Brain Diff** | Semantic diff between two brains. Venn-diagram SVG + English narrative. "What did Team A learn that Team B didn't?" |
+JSON output:
 
 ```bash
-shadow-brain dna card --out my-brain.svg                    # 🧬 generate your DNA card
-shadow-brain replay export --format svg --out timeline.svg  # 🎬 scrubbable timeline
-shadow-brain hive-voice ask "Server Components by default?" # 🗳️ multi-model vote
-shadow-brain capsule freeze --label "pre-redesign"          # ⏰ freeze a snapshot
-shadow-brain brain-diff compare brain-a/ brain-b/           # 🔬 semantic diff
-```
-
-### 🎁 14 More Advanced Features
-
-| | | | |
-|---|---|---|---|
-| 🎵 **Brain Cinema** — auto-procedural 60-sec SVG video | 🎼 **Brain Sonification** — your codebase as music (WAV) | 🏆 **Brain Trophies** — 25 achievements w/ share cards | 🎁 **Brain Holiday Card** — year-in-review SVG |
-| 🧭 **Brain Coach** — 10 proactive idle-suggestion rules | 🗺️ **Brain Quest** — 5 gamified onboarding adventures | 📓 **Brain Notebook** — Jupyter-style brain explorer | ⚡ **Brain Reflex** — local-model inline completion |
-| 🔥 **Brain Roast** — comedy code review (6 personas) | 🔮 **Brain Tarot** — 78-card divination from git+brain | 🎨 **Brain ASCII** — terminal-art brain (6 styles) | 😂 **Brain Memes** — auto-generated dev memes (10 templates) |
-| 🌌 **Brain 3D** — rotatable Three.js graph viewer | 💞 **Brain Doppelganger** — find your codebase's twin | | |
-
-### 🧠 10 Brain-Quality Upgrades (the engineering wins)
-
-| Recall quality | Memory arch | Efficiency | Intelligence | Size + Learning |
-|---|---|---|---|---|
-| **Rerank** (BM25 + cosine hybrid) | **Memory Tiers** (episodic/semantic) | **Working Memory** (LRU + predictive prefetch) | **Contradictions** (46 polarity pairs) | **Quantize** (int8 vectors, 4× smaller, 0.000298 mean error) |
-| **Query Expander** (synonyms + abbrev + HyDE) | **Consolidator** (dedup + abstractions) | **Recall Cache** (bloom filter, 65k bits, ~4% FP @ 10k keys) | **Graph Walker** (5 edge types, 3-hop BFS) | **Active Learner** (accept/reject feedback bias) |
-
-### ⚙️ Production Infrastructure
-
-- **Real ANN vector index** (`embeddings-v2.ts`) — HNSW-style graph, M=8, sub-100ms recall over 10k vectors, sharded persistence (5MB cap), auto-pulls `nomic-embed-text` from Ollama on first run
-- **Constitution layer** — `<project>/.shadow-brain/constitution.md` parser + hot-reload + injection
-- **Confidence Gate** — active output filter, Brier score + ECE stats
-- **Multimodal vision** — Ollama llava / llava-llama3 / bakllava ingestion
-- **Markdown brain export/import** — git-trackable `.shadow-brain.md` round-trip
-- **OpenTelemetry-lite tracing** — OTel-compatible JSONL, daily rotation
-- **LoRA distillation pipeline** (`tools/lora-pipeline/`) — turn your brain into a Qwen2.5-Coder-1.5B adapter
-- **SWE-Bench-Lite harness** (`tools/swe-bench-lite/`) — 10 curated bugs, brain-on vs brain-off, statistical scoring
-- **30-second demo**: `npx @theihtisham/agent-shadow-brain demo`
-
-### 📊 v6.0.2 by the numbers
-
-| | |
-|---|---|
-| New brain modules | **35** (25 features + 10 quality stack) |
-| New CLI command groups | **27** |
-| New LOC | **~16,000** (TypeScript) |
-| New npm dependencies | **0** |
-| Sample artifacts shipped | **7** (DNA card, Replay timeline, Cinema, Holiday wrapped, Tarot, Trophy wall, 3D viewer HTML) |
-| Quantization roundtrip error | **0.000298** (16× better than spec) |
-| TypeScript errors | **0** |
-
-**Full release notes:** [docs/launch/RELEASE_NOTES_v6.0.2.md](docs/launch/RELEASE_NOTES_v6.0.2.md)
-**Strategic roadmap (v7+):** [docs/ROADMAP-v7.md](docs/ROADMAP-v7.md)
-**Launch playbook:** [docs/VIRAL-PLAYBOOK.md](docs/VIRAL-PLAYBOOK.md)
-
----
-
-## 🔥 Why Shadow Brain? (the 60-second pitch)
-
-| Without Shadow Brain | With Shadow Brain v6 |
-|---|---|
-| Every new session → agent starts from zero | 2K-token briefing injected **before** the first prompt |
-| Cursor learns X → Claude doesn't know | **One singleton brain** every agent shares |
-| Claude Task spawns sub-agent → sub-agent starts blind | **SABB** injects focused context slivers into every sub-agent |
-| You can't explain *why* the AI made a choice | **Causal Memory Chains** render the full DAG of causes |
-| Two agents touching the same file = merge hell | **Collision Detective** catches it in real time |
-| Agents work, then go idle — wasted compute | **Dream Engine** reflects during idle, runs counterfactuals |
-| No verifiable record of agent decisions | **Ed25519-signed Reputation Ledger** — tamper-proof receipts |
-| Token bills explode across Opus / GPT / Gemini | **Token Economy** routes to cheapest model that passes confidence |
-| Needs its own API key for everything | **Agent-proxy mode** reuses your existing Claude/Cursor/Codex config |
-| Every tool runs hot, every key leaks | **Air-Gap mode** + ChaCha20 encryption at rest |
-
----
-
-## 🌟 22 Novel Modules — None Exist in Any Other Tool
-
-> *This isn't a wrapper around someone else's API. All 22 are first-party research-grade implementations, persisted to disk, with real tests.*
-
-### 🧠 Cognition
-1. **Sub-Agent Brain Bridge (SABB)** — sync brain context into Claude Task / Cursor Composer / CrewAI / LangGraph / AutoGen sub-agents
-2. **Causal Memory Chains** — every decision links to its causes; Graphviz DOT export
-3. **Dream Engine** — idle-time reflection: revisit / counterfactual / consolidation / contradiction / pattern-discovery
-4. **Swarm Debate Protocol** — pro / con / arbiter sub-agents for critical decisions
-5. **Pre-Mortem Assistant** — surfaces past failures from *your* project before you start
-6. **Branch Brains** — git-branch-aware memory context
-
-### 🔍 Transparency & Trust
-7. **Agent Reputation Ledger** — Ed25519-signed receipts, portable accuracy score
-8. **Attention Heatmap** — weighted attribution showing which memories shaped a decision
-9. **Confidence Calibration Monitor** — Brier scores + automatic trust-weighting
-10. **Formal Verification Bridge** — natural-language rules → ESLint / Semgrep / LSP diagnostics
-11. **Agent Collision Detective** — real-time overlap detection with advisory locks
-
-### 💰 Economy & Memory
-12. **Token Economy Engine** — cross-agent spend, savings suggestions, routing advice
-13. **Cost-Aware Sub-Agent Spawner** — auto-route trivial tasks to cheaper models
-14. **Forgetting Curve + Sleep Consolidation** — Ebbinghaus-inspired biological memory
-
-### 🔒 Privacy & Safety
-15. **Air-Gap Mode** — zero outbound network, localhost-only
-16. **E2E Encryption** — ChaCha20-Poly1305 at rest
-17. **Hallucination Quarantine** — isolate suspect memories, auto-expire in 7 days
-
-### ✨ Delight & Network Effects
-18. **Voice Mode** — natural-language intent parser for transcripts
-19. **Brain Garden** — animated visualization of memory as a living constellation
-20. **PR Auto-Review** — GitHub PR comments citing project memories
-21. **Team Brain Sync (WebRTC)** — peer-to-peer shared brain, no server
-22. **Brain Exchange** — export / import curated shareable brain slices
-
-### ⚡ Accelerators
-- **Local-First LLM** — Ollama default; optional Anthropic / OpenAI / OpenRouter / Moonshot / Gemini / DeepSeek / Mistral
-- **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
-
----
-
-## 🖥️ Complete Web Control Dashboard
-
-Start it:
+shadow-brain live-brain status . --json
+```
+
+### Agent Briefing
+
+Generate a markdown briefing for a fresh agent session:
+
 ```bash
-shadow-brain dash .
-# → http://localhost:7341/
+shadow-brain live-brain brief . -o SHADOW_BRAIN_AGENT_BRIEF.md
 ```
 
-**28 tabs. Real-time data. Full control.** Every feature has live monitoring + interactive controls. Preview:
+The briefing includes:
 
-| | | |
-|---|---|---|
-| ![Overview](docs/launch/screenshots/01-overview.png) | ![Live Graph](docs/launch/screenshots/02-graph.png) | ![Agents](docs/launch/screenshots/03-agents.png) |
-| **Overview** — live counters, charts | **Live Graph** — animated signal flow | **Agents** — connect / disconnect per agent |
-| ![Chat](docs/launch/screenshots/04-chat.png) | ![Memory](docs/launch/screenshots/05-memory.png) | ![SABB](docs/launch/screenshots/07-sabb.png) |
-| **Chat with Brain** — RAG with citations | **Memory Browser** — semantic search | **SABB** — sliver generator + quarantine |
-| ![Causal](docs/launch/screenshots/08-causal.png) | ![Dream](docs/launch/screenshots/10-dream.png) | ![Reputation](docs/launch/screenshots/11-reputation.png) |
-| **Causal Chains** — traceable decisions | **Dream Engine** — reflection insights | **Reputation** — Ed25519 leaderboard |
-| ![Tokens](docs/launch/screenshots/19-tokens.png) | ![Models](docs/launch/screenshots/27-models.png) | ![Command](docs/launch/screenshots/29-command-palette.png) |
-| **Token Economy** — $ saved live | **Models & Intelligence** — 8 providers | **⌘K Command Palette** |
+- rules for agents
+- top source-backed memories
+- memory warnings
+- recall health
+- commands agents should run next
 
-**→ [Browse all 29 tab screenshots](docs/launch/screenshots/)**
+### Recall Eval
 
-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.
+Check whether the brain can retrieve useful memories for common agent tasks:
 
----
+```bash
+shadow-brain live-brain eval .
+```
 
-## 🧩 Works With Every AI Coding Agent
+Custom eval queries use pipe separators:
 
-| Agent | Adapter | Hook target |
-|---|---|---|
-| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | ✅ Native | `~/.claude/settings.json` hooks.SessionStart |
-| [Cursor](https://cursor.sh/) | ✅ Native | `.cursor/rules/shadow-brain.md` + MCP |
-| [Cline](https://github.com/cline/cline) | ✅ Native | VS Code globalStorage MCP |
-| [Codex](https://github.com/openai/codex) | ✅ Native | `~/.codex/config.json` |
-| [GitHub Copilot](https://github.com/features/copilot) | ✅ Native | `.github/copilot-instructions.md` |
-| [Windsurf](https://codeium.com/windsurf) | ✅ Native | `.windsurfrules` + MCP |
-| [Kilo Code](https://kilocode.ai/) | ✅ Native | `~/.kilocode/settings.json` |
-| [Roo Code](https://roocode.com/) | ✅ Native | `~/.roocode/mcp.json` |
-| [OpenCode](https://github.com/opencode-ai/opencode) | ✅ Native | `AGENT.md` |
-| [Aider](https://aider.chat/) | ✅ Native | `.aider.conf.yml` |
+```bash
+shadow-brain live-brain eval . --queries "current blocker|do not repeat|verified command"
+```
 
-**Custom agent?** Add its config path in the dashboard "Custom Agent Paths" panel — Shadow Brain will auto-read its provider + model + API key.
+### Memory Hygiene
 
-**Sub-agent frameworks supported by SABB:** Claude Task, Cursor Composer, Cline Sub-step, CrewAI, LangGraph, AutoGen, generic.
+List concrete cleanup and learning actions:
 
----
+```bash
+shadow-brain live-brain hygiene .
+```
+
+This highlights missing sources, stale memories, duplicates, weak recall, and missing project-scoped memories.
 
-## 🤖 Use Your Own LLM — or Your Agent's Already-Configured One
+### Training/Eval Export
 
-Shadow Brain's **ModelRegistry** supports 8 providers out of the box:
+Export source-backed memories as JSONL:
 
-**Ollama (default, local, free)** · **Anthropic Claude** · **OpenAI** · **OpenRouter** · **Moonshot / Kimi** · **Google Gemini** · **DeepSeek** · **Mistral**
+```bash
+shadow-brain live-brain train-pack . --out shadow-brain-training.jsonl
+```
 
-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**.
+This is useful for:
 
-Auto-discovery reads every agent config on your machine so you never retype a key.
+- retrieval evals
+- local distillation experiments
+- supervised fine-tuning datasets
+- memory regression tests
 
----
+The export is only data preparation. You choose the downstream training/eval tool.
 
-## 📊 Real Numbers
+## Core Memory Commands
 
-| Metric | Value |
-|---|---|
-| Brain modules | **48** |
-| CLI commands | **90+** |
-| MCP tools | **60+** |
-| REST endpoints | **50+** |
-| Tests passing | **148 / 148** |
-| TypeScript errors | **0** |
-| Supported agents | **10** (plus custom) |
-| Supported LLM providers | **8** (plus agent-proxy) |
-| Novel features nobody else has | **22** |
-| License | **MIT** |
-| Cost to run | **$0 forever** (local-first) |
+Recall from the global brain:
 
----
+```bash
+shadow-brain global recall --query "current blocker next step" --json --limit 8
+```
 
-## 🚀 30-Second Quickstart
+Show global stats:
 
 ```bash
-# 1. Install
-npx @theihtisham/agent-shadow-brain@latest attach-all
+shadow-brain global stats
+```
+
+Create a source-backed resume seed:
 
-# 2. Launch the dashboard
-shadow-brain dash .
-# → open http://localhost:7341/
+```bash
+shadow-brain resume-seed . -o SHADOW_BRAIN_RESUME_SEED.md
+```
 
-# 3. Seed the brain (optional — populates example data)
-shadow-brain reputation sign --agent claude-code --ver 4.7 --project demo \
-  --decision "use bcrypt cost 12 for all password hashing" \
-  --category security --confidence 0.92
+Show what a project has learned:
 
-# 4. Every new AI agent session automatically gets context injected
+```bash
+shadow-brain timeline . --limit 30
 ```
 
-**That's it.** Open any project in Claude Code / Cursor / any supported agent — Shadow Brain is already running under the hood.
+Create a cross-agent handoff packet:
 
----
+```bash
+shadow-brain handoff codex claude-code . --task "continue release verification"
+```
 
-## 🧪 The Hive Mind Explainer (2 minutes)
+Record a durable memory from a script:
 
-[![Shadow Brain Hive Mind Explainer — 2 minutes](banner.svg)](https://github.com/theihtisham/agent-shadow-brain/raw/main/docs/launch/shadow-brain-motion-explainer-narrated.mp4)
+```bash
+node tools/record-global-memory.mjs ^
+  --project-dir "." ^
+  --project-name "my-project" ^
+  --agent codex ^
+  --category "project.lesson" ^
+  --importance 0.8 ^
+  --tags "memory,release" ^
+  --sources "README.md,CHANGELOG.md" ^
+  --content "Keep release notes source-backed and verify npm metadata before publish."
+```
 
-**[▶ 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.
+## Dashboard
 
-Local file: `docs/launch/shadow-brain-motion-explainer-narrated.mp4` (2:05 · 1080p · narrated).
+Start the local dashboard:
 
----
+```bash
+shadow-brain dash . --no-open --port 7341
+```
 
-## 📖 CLI Reference (top commands)
+For a fast UI/API-only launch on a large repo:
 
 ```bash
-# Attachment + lifecycle
-shadow-brain attach-all          # wire every detected agent
-shadow-brain detach-all          # remove every hook
-shadow-brain audit-hooks         # list what's installed
-shadow-brain dash .              # launch web dashboard at :7341
-shadow-brain mcp                 # start MCP server at :7342
-
-# v6 Hive Mind
-shadow-brain hive status         # cross-module status
-shadow-brain subagent sliver --parent claude-code --task "refactor auth"
-shadow-brain causal trace <id>   # render ancestor DAG
-shadow-brain dream run           # trigger idle reflection now
-shadow-brain debate "Redis or Postgres?" --context "10k users"
-shadow-brain premortem "migrate auth to passkeys"
-shadow-brain reputation sign --agent claude-code --ver 4.7 --project X \
-  --decision "..." --category security --confidence 0.92
-shadow-brain reputation badge claude-code --ver 4.7
-
-# Memory + analytics
-shadow-brain global recall --keywords "auth"
-shadow-brain tokens report       # cross-agent spend + savings
-shadow-brain forget consolidate  # run sleep cycle
-shadow-brain formal generate "always use parameterized SQL"
-shadow-brain formal export-eslint
-
-# Privacy + trust
-shadow-brain airgap enable --policy strict
-shadow-brain encrypt file ~/.shadow-brain/global.json --passphrase ...
-shadow-brain quarantine list
-
-# Sharing
-shadow-brain exchange export --name "react-expert-v1" --tags react,auth
-shadow-brain exchange import ~/brain-packs/react-expert-v1.json
-
-# Full list
-shadow-brain --help
+shadow-brain dash . --no-open --no-analysis --host 127.0.0.1 --port 7341
 ```
 
----
+Open:
+
+```text
+http://127.0.0.1:7341
+```
+
+The v6 dashboard includes a **Live Brain** tab for memory health, source coverage, recall evals, hygiene actions, top memories, and the generated agent briefing.
+
+It also includes:
+
+- **Memory Browser intelligence cards** for total memories, source coverage, fresh learning, seed queue, top categories, agent coverage, and top tags.
+- **Memory Seeder** for controlled research-to-memory workflows. Drafts stay out of the global brain until approval is complete.
+- **Token Economy accuracy split**: current runtime agent is shown separately from historical model spend, so old Claude/Cursor spend records do not imply the dashboard is running that agent.
+
+### Realtime Activity (new in 6.1.0)
+
+The dashboard now streams brain activity live over its WebSocket instead of polling. Memory writes, dreams, seed drafts/commits, collisions, sub-agent spawns, and consolidation cycles appear the instant they happen.
 
-## 🎯 Tweetable Talking Points
+- **Live Pulse** card on the Overview with a streaming mini-feed and an events/min rate.
+- **Activity Log** tab with filter chips, a pulsing LIVE badge, pause/resume, clear, search, and an events/min sparkline.
+- **Connection indicator** in the header — green when the realtime socket is live, amber while reconnecting.
+- **Cross-process aware**: a memory written by an agent in a *different* terminal is picked up by watching `~/.shadow-brain/global.json`, so the feed reflects the whole machine, not just this process.
 
-> *"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."*
+Polling remains as a 15-second reconciliation fallback; live events arrive in well under a second.
 
-> *"Every AI decision Shadow Brain makes is Ed25519-signed. Every cause is traced. Every collision is caught before it happens. Free forever."*
+### Intelligence Hub — Memory Constellation (new in 6.2.0)
 
-> *"22 novel features nobody else has. Free. Open source. Local-first. `npx @theihtisham/agent-shadow-brain`."*
+A new **Intelligence** tab turns the brain into an interactive graph. Every memory, project, agent, and tag is a node in a force-directed **Memory Constellation**, sized by importance (PageRank blended with each memory's own score) and linked by project, author, tags, and shared-tag relatedness.
 
----
+- **Interactive**: scroll to zoom, drag to pan, click a node to focus its neighborhood and open a detail drawer; hover for a tooltip.
+- **Filters + search** by node type (memory / project / agent / tag).
+- **Live**: new memories pulse into the graph over the realtime stream.
+- **Analytics strip**: source-coverage gauge, agent-contribution and category charts, tag cloud, and a recent-memory feed.
+- Works instantly on your existing `~/.shadow-brain/global.json` — no project analysis or setup step.
 
-## 🛠️ For Contributors
+Several previously sparse tabs were also rebuilt with real visualizations: **Pre-Mortem** (risk matrix + failure cards), **Attention** (weighted heat bars), **Calibration** (Brier/trust chart), **Reputation** (trust rings), **Causal Chains** (node-link DAG), and **Branch Brains** (stat cards).
+
+Constellation API:
+
+```text
+GET /api/v6/memory-graph
+```
+
+
+Memory seeding API:
+
+```text
+GET  /api/v6/seed-drafts
+POST /api/v6/seed-draft
+POST /api/v6/seed-approve
+POST /api/v6/seed-reject
+POST /api/v6/seed-commit
+GET  /api/v6/memory-intelligence
+```
+
+Useful API endpoints:
+
+```text
+GET/POST /api/v6/live-brain
+GET/POST /api/v6/resume-pack
+GET/POST /api/v6/ww2br-recall
+GET/POST /api/v6/memory-browser
+```
+
+Example:
 
 ```bash
-git clone https://github.com/theihtisham/agent-shadow-brain.git
-cd agent-shadow-brain
-npm install
-npm run build
-npm test                # 148/148 tests
-npm run dev             # ts-node dev mode
+curl "http://127.0.0.1:7341/api/v6/live-brain?projectDir=C:/path/to/project"
+```
+
+## MCP Tools
+
+The MCP server exposes memory and agent-control tools for compatible clients.
+
+New in 6.0.3:
+
+- `live_brain_status`
+- `live_brain_brief`
+- `live_brain_train_pack`
+
+Existing useful tools include:
+
+- `global_recall`
+- `global_stats`
+- `global_timeline`
+- `subconscious_inject`
+- `agent_handoff`
+- `firewall_check`
 
-# Rebuild the explainer video
-node tools/record-motion-explainer.mjs
+Start MCP from the dashboard API or existing CLI/server integration, depending on your setup.
 
-# Capture fresh dashboard screenshots
-node tools/capture-screenshots.mjs
+## How Agents Should Use It
 
-# Seed the brain with demo data
-node tools/seed-brain.mjs
+Recommended workflow for complex work:
+
+1. Run `shadow-brain live-brain status <project>`.
+2. Generate or read a live briefing.
+3. Verify current project docs and source files.
+4. Work normally.
+5. Record only durable, source-backed lessons after proof.
+6. Run recall evals when memory quality starts to drift.
+
+Good memories are short, action-oriented, and source-backed:
+
+```text
+[lesson:release-readme-v1] Before publishing, verify package.json version, package-lock root version, README install commands, build output, and npm pack contents.
+Sources: package.json; package-lock.json; README.md
+Tags: release,npm,verification
 ```
 
-Issues, PRs, discussions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
+Bad memories are vague:
 
----
+```text
+Make project better.
+```
 
-## 📚 Documentation
+## Local Data
 
-- **[CHANGELOG.md](CHANGELOG.md)** — release notes
-- **[docs/versions/v6.0.0.md](docs/versions/v6.0.0.md)** — v6 release details
-- **[docs/launch/HIVEMIND_VIDEO.md](docs/launch/HIVEMIND_VIDEO.md)** — video production pipeline
-- **[docs/launch/screenshots/](docs/launch/screenshots/)** — all 29 dashboard screenshots
-- **[SECURITY.md](SECURITY.md)** — security policy
-- **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)** — community guidelines
+Default global brain:
 
----
+```text
+~/.shadow-brain/global.json
+```
 
-## 💬 Community
+Project-local generated files may include:
 
-- **[GitHub Issues](https://github.com/theihtisham/agent-shadow-brain/issues)** — bug reports, feature requests
-- **[GitHub Discussions](https://github.com/theihtisham/agent-shadow-brain/discussions)** — questions, ideas, show-and-tell
-- **[GitHub Releases](https://github.com/theihtisham/agent-shadow-brain/releases)** — download the explainer MP4 + release assets
+```text
+SHADOW_BRAIN_AGENT_BRIEF.md
+SHADOW_BRAIN_RESUME_SEED.md
+shadow-brain-training.jsonl
+```
 
-**If Shadow Brain makes your AI agents smarter, star the repo ⭐**
+Do not store secrets, API keys, passwords, private keys, or raw credentials in memory content, metadata, tags, prompts, reports, or exported training data.
 
----
+## Development
 
-## ⭐ Stargazers Over Time
+```bash
+npm install
+npm run build
+npm test
+```
 
-[![Star History Chart](https://api.star-history.com/svg?repos=theihtisham/agent-shadow-brain&type=Date)](https://star-history.com/#theihtisham/agent-shadow-brain&Date)
+Focused tests:
 
----
+```bash
+npx vitest run tests/brain/live-brain.test.ts tests/brain/context-continuity.test.ts
+```
 
-## 📜 License
+On Windows PowerShell, if execution policy blocks `npm.ps1`, use:
 
-**MIT** — see [LICENSE](LICENSE).
+```powershell
+npm.cmd run build
+npx.cmd vitest run tests\brain\live-brain.test.ts
+```
 
-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.
+## Release Checklist
 
----
+For a 6.0.3 release:
 
-<div align="center">
+```bash
+npm run build
+npm test
+npm pack --dry-run
+```
 
-### Built by [@theihtisham](https://github.com/theihtisham)
+Then publish only after verifying the package contents:
 
-<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>
-<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>
+```bash
+npm publish --access public
+```
 
-### The Hive Mind for every AI coding agent on your machine.
+GitHub release should include:
 
-**`npx @theihtisham/agent-shadow-brain@latest attach-all`**
+- this README
+- `CHANGELOG.md`
+- `docs/launch/RELEASE_NOTES_v6.0.3.md`
+- `docs/launch/RELEASE_CHECKLIST_v6.0.3.md`
+- build/test output
+- npm package dry-run output
 
-<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>
+## License
 
-</div>
+MIT