@theihtisham/agent-shadow-brain 6.0.2 → 6.0.3

package/docs/launch/RELEASE_NOTES_v6.0.3.md

@@ -0,0 +1,111 @@
+# Shadow Brain v6.0.3
+
+Date: 2026-06-03
+
+v6.0.3 is a practical memory-quality release. It focuses on making Shadow Brain useful for real long-running agent work instead of adding more marketing claims.
+
+## Highlights
+
+- Added the Live Brain module.
+- Added live memory health reports.
+- Added source coverage, stale-memory, duplicate, and low-quality memory checks.
+- Added recall evals for common agent workflows.
+- Added markdown agent briefings for fresh sessions and handoffs.
+- Added JSONL training/eval pack export.
+- Added dashboard API route and dashboard Live Brain tab for Live Brain reports.
+- Added Memory Seeder: dashboard/API draft creation, source capture, user approval, agent approval, dual approval, rejection, and seed-to-global-brain commit.
+- Added Memory Intelligence API and dashboard cards for source coverage, freshness, categories, agents, tags, recent writes, and seed queue counts.
+- Fixed Token Economy dashboard wording and data split so the active runtime agent is shown separately from historical model spend.
+- Added MCP tools for Live Brain status, briefing, and training-pack export.
+- Added dashboard `--host` and `--no-analysis` controls for reliable local UI launches on large repos.
+- Fixed CLI config merging so commands that request one-shot mode can actually disable watch mode.
+- Rewrote the README to describe real behavior and release workflow.
+- Updated npm metadata to 6.0.3 with a realistic package description.
+
+## New CLI Commands
+
+```bash
+shadow-brain live-brain status .
+shadow-brain live-brain brief . -o SHADOW_BRAIN_AGENT_BRIEF.md
+shadow-brain live-brain eval .
+shadow-brain live-brain hygiene .
+shadow-brain live-brain train-pack . --out shadow-brain-training.jsonl
+```
+
+Short alias:
+
+```bash
+shadow-brain live status .
+```
+
+## New API
+
+```text
+GET/POST /api/v6/live-brain
+GET      /api/v6/memory-intelligence
+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
+```
+
+Use `format=markdown` to return the agent briefing instead of JSON.
+
+## New Dashboard Surface
+
+The v6 dashboard now includes a Live Brain tab showing memory quality, source coverage, recall eval results, recommended hygiene actions, top memories, and the markdown briefing that agents can use during handoffs.
+
+The Memory Browser now includes live memory intelligence: total memory count, source coverage, fresh learning, seed queue, top categories, agent coverage, and tags.
+
+The Memory Seeder tab turns research into durable memory safely. A draft can be prepared by a selected research agent, checked against sources and existing memory, then approved by the user, by a selected agent, or by both before it is written to the global brain.
+
+## New MCP Tools
+
+- `live_brain_status`
+- `live_brain_brief`
+- `live_brain_train_pack`
+
+## What "Training" Means Here
+
+Shadow Brain does not train remote model weights. The new training pack exports source-backed memory examples as JSONL so users can run their own eval, distillation, or local fine-tuning workflows.
+
+## Verification
+
+Validated locally:
+
+```bash
+npm.cmd run build
+npm.cmd test
+npm.cmd pack --dry-run
+```
+
+Result:
+
+- TypeScript build passed.
+- Full Vitest suite passed.
+- npm package dry run passed.
+
+## Files Added
+
+- `src/brain/live-brain.ts`
+- `src/brain/memory-seeder.ts`
+- `tests/brain/live-brain.test.ts`
+- `tests/brain/memory-seeder.test.ts`
+- `docs/launch/RELEASE_NOTES_v6.0.3.md`
+
+## Files Updated
+
+- `README.md`
+- `CHANGELOG.md`
+- `package.json`
+- `package-lock.json`
+- `src/cli.ts`
+- `src/index.ts`
+- `src/dashboard/server.ts`
+- `src/dashboard/v6-dashboard-html.ts`
+- `src/brain/context-continuity.ts`
+- `src/brain/mcp-server.ts`
+- `src/brain/auto-update.ts`
+- `src/brain/brain-portability.ts`
+- `src/brain/orchestrator.ts`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@theihtisham/agent-shadow-brain",
-  "version": "6.0.2",
-  "description": "Hive Mind for AI coding agents — the first open-source brain that works with sub-agents. v6.0.2 ships 19 world-first features: 5 viral artifacts (Brain Replay timeline, Brain DNA fingerprint card, Hive Voice consensus chart, Brain Time Capsule snapshots, Brain Diff Venn) + 14 advanced features (Brain Cinema auto-video, Brain Sonification codebase-as-music, Brain Trophies achievements, Brain Holiday Card year-in-review, Brain Coach proactive suggestions, Brain Quest gamified onboarding, Brain Notebook Jupyter-style explorer, Brain Reflex local-model inline completion, Brain Roast comedy code review, Brain Tarot 78-card divination, Brain ASCII terminal art, Brain Memes auto-generator, Brain 3D rotatable graph, Brain Doppelganger codebase-matching) + production infrastructure (real HNSW vector index, Constitution layer, Confidence Gate, multimodal llava vision, Markdown brain export, OTel-lite tracing, LoRA distillation pipeline, SWE-Bench eval harness). On top of v6.0's 22 features (SABB, causal chains, dream engine, swarm debate, branch brains, air-gap, voice mode, PR auto-review, team P2P sync). Local-first, free, MIT, zero telemetry.",
+  "version": "6.0.3",
+  "description": "Local-first memory and coordination layer for AI coding agents. Shadow Brain stores source-backed project lessons, recalls them across Codex, Claude Code, Cursor, Cline, OpenCode, and other tools, generates resume briefings, audits memory quality, exports training/eval JSONL, and exposes CLI/API/MCP surfaces with zero telemetry.",
   "main": "dist/index.js",
   "exports": {
     ".": "./dist/index.js"
@@ -14,9 +14,11 @@
     "build": "tsc",
     "dev": "ts-node src/cli.ts",
     "watch": "tsc --watch",
-    "test": "vitest run",
-    "lint": "tsc --noEmit",
-    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "lint": "tsc --noEmit",
+    "verify": "npm run build && npm test",
+    "pack:dry": "npm pack --dry-run",
+    "prepublishOnly": "npm run build",
     "postinstall": "node dist/brain/auto-setup.js 2>>~/.shadow-brain/install.log || true"
   },
   "keywords": [
@@ -135,9 +137,14 @@
     "brain-exchange",
     "local-first",
     "ollama",
-    "forgetting-curve",
-    "sleep-consolidation"
-  ],
+    "forgetting-curve",
+    "sleep-consolidation",
+    "live-brain",
+    "resume-pack",
+    "memory-quality",
+    "training-jsonl",
+    "source-backed-memory"
+  ],
   "author": "ihtisham",
   "license": "MIT",
   "dependencies": {
@@ -170,11 +177,16 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "files": [
-    "dist/**/*",
-    "README.md",
-    "LICENSE"
-  ],
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "docs/launch/RELEASE_CHECKLIST_v6.0.3.md",
+    "docs/launch/RELEASE_NOTES_v6.0.3.md",
+    "tools/export-resume-pack.mjs",
+    "tools/record-global-memory.mjs"
+  ],
   "publishConfig": {
     "access": "public"
   },

package/tools/export-resume-pack.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { generateContextResumePack } from '../dist/brain/context-continuity.js';
+import { getGlobalBrain, GlobalBrain } from '../dist/brain/global-brain.js';
+
+function readArg(name, fallback = undefined) {
+  const index = process.argv.indexOf(name);
+  if (index < 0) return fallback;
+  return process.argv[index + 1] ?? fallback;
+}
+
+function readFlag(name) {
+  return process.argv.includes(name);
+}
+
+const projectDir = path.resolve(readArg('--project-dir', process.cwd()));
+const out = readArg('--out', '');
+const format = String(readArg('--format', 'markdown')).toLowerCase();
+const limit = Number.parseInt(readArg('--limit', '12'), 10);
+const globalFallback = readFlag('--global-fallback');
+
+const brain = getGlobalBrain();
+await brain.init();
+
+try {
+  const projectId = GlobalBrain.projectIdFor(projectDir);
+  let entries = brain.recall({ projectId, minImportance: 0, limit: 500 });
+  let projectScoped = true;
+  if (!entries.length && globalFallback) {
+    projectScoped = false;
+    entries = brain.recall({ minImportance: 0, limit: 500 });
+  }
+
+  const pack = generateContextResumePack({
+    projectDir,
+    projectId,
+    projectName: path.basename(projectDir),
+    entries,
+    maxMemories: Number.isFinite(limit) ? Math.max(1, Math.min(30, limit)) : 12,
+  });
+  const payload = format === 'json'
+    ? JSON.stringify({ ...pack, projectScoped }, null, 2)
+    : pack.markdown;
+
+  if (out) {
+    const outPath = path.resolve(out);
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    fs.writeFileSync(outPath, payload, 'utf-8');
+    console.log(JSON.stringify({ ok: true, out: outPath, format, projectScoped, memoryCount: entries.length }, null, 2));
+  } else {
+    process.stdout.write(payload);
+  }
+} finally {
+  await brain.shutdown();
+}

package/tools/record-global-memory.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { getGlobalBrain } from '../dist/brain/global-brain.js';
+
+function readArg(name, fallback = undefined) {
+  const index = process.argv.indexOf(name);
+  if (index < 0) return fallback;
+  return process.argv[index + 1] ?? fallback;
+}
+
+function readFlag(name) {
+  return process.argv.includes(name);
+}
+
+function splitList(value) {
+  return (value ?? '')
+    .split(',')
+    .map(item => item.trim())
+    .filter(Boolean);
+}
+
+const projectDir = path.resolve(readArg('--project-dir', process.cwd()));
+const projectName = readArg('--project-name', path.basename(projectDir));
+const agentTool = readArg('--agent', 'codex');
+const category = readArg('--category', 'learning');
+const content = readArg('--content');
+const importance = Number.parseFloat(readArg('--importance', '0.75'));
+const tags = splitList(readArg('--tags', ''));
+const sources = splitList(readArg('--sources', ''));
+const seedId = readArg('--seed-id', '');
+
+if (!content) {
+  console.error('Missing --content "memory text"');
+  process.exit(2);
+}
+
+const brain = getGlobalBrain();
+await brain.init();
+
+try {
+  const projectId = brain.registerProject(projectDir, projectName);
+  brain.registerAgent(agentTool);
+
+  if (seedId) {
+    const existing = brain.recall({ keywords: [seedId], category, limit: 1 });
+    if (existing.length && !readFlag('--force')) {
+      console.log(JSON.stringify({ skipped: true, seedId, existingId: existing[0].id }, null, 2));
+      process.exit(0);
+    }
+  }
+
+  const id = brain.writeSync({
+    projectId,
+    projectName,
+    agentTool,
+    category,
+    content: seedId ? `[seed:${seedId}] ${content}` : content,
+    importance: Number.isFinite(importance) ? importance : 0.75,
+    metadata: {
+      seedId: seedId || undefined,
+      tags,
+      sources,
+      recordedBy: 'tools/record-global-memory.mjs',
+      recordedAt: new Date().toISOString(),
+    },
+  });
+
+  await brain.sync();
+  console.log(JSON.stringify({ id, projectId, projectName, category, tags, sources }, null, 2));
+} finally {
+  await brain.shutdown();
+}