@theihtisham/agent-shadow-brain 7.0.0 → 7.2.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.
Files changed (79) hide show
  1. package/CHANGELOG.md +18 -0
  2. package/README.md +36 -396
  3. package/dist/brain/auto-update.js +1 -1
  4. package/dist/brain/brain-portability.js +1 -1
  5. package/dist/brain/context-assembly.d.ts +58 -0
  6. package/dist/brain/context-assembly.d.ts.map +1 -0
  7. package/dist/brain/context-assembly.js +207 -0
  8. package/dist/brain/context-assembly.js.map +1 -0
  9. package/dist/brain/feature-settings.d.ts +53 -0
  10. package/dist/brain/feature-settings.d.ts.map +1 -0
  11. package/dist/brain/feature-settings.js +232 -0
  12. package/dist/brain/feature-settings.js.map +1 -0
  13. package/dist/brain/global-brain.d.ts +1 -0
  14. package/dist/brain/global-brain.d.ts.map +1 -1
  15. package/dist/brain/global-brain.js +3 -3
  16. package/dist/brain/global-brain.js.map +1 -1
  17. package/dist/brain/mcp-server.d.ts +4 -0
  18. package/dist/brain/mcp-server.d.ts.map +1 -1
  19. package/dist/brain/mcp-server.js +81 -5
  20. package/dist/brain/mcp-server.js.map +1 -1
  21. package/dist/brain/orchestrator.js +1 -1
  22. package/dist/brain/subconscious.d.ts +19 -24
  23. package/dist/brain/subconscious.d.ts.map +1 -1
  24. package/dist/brain/subconscious.js +77 -218
  25. package/dist/brain/subconscious.js.map +1 -1
  26. package/dist/brain/task-workflow.d.ts +22 -0
  27. package/dist/brain/task-workflow.d.ts.map +1 -0
  28. package/dist/brain/task-workflow.js +182 -0
  29. package/dist/brain/task-workflow.js.map +1 -0
  30. package/dist/brain/workflow-skills.d.ts +86 -0
  31. package/dist/brain/workflow-skills.d.ts.map +1 -0
  32. package/dist/brain/workflow-skills.js +514 -0
  33. package/dist/brain/workflow-skills.js.map +1 -0
  34. package/dist/cli.js +6 -2
  35. package/dist/cli.js.map +1 -1
  36. package/dist/context-cli.d.ts +3 -0
  37. package/dist/context-cli.d.ts.map +1 -0
  38. package/dist/context-cli.js +54 -0
  39. package/dist/context-cli.js.map +1 -0
  40. package/dist/dashboard/server.d.ts +1 -0
  41. package/dist/dashboard/server.d.ts.map +1 -1
  42. package/dist/dashboard/server.js +32 -4
  43. package/dist/dashboard/server.js.map +1 -1
  44. package/dist/dashboard/v6-dashboard-html.d.ts +1 -1
  45. package/dist/dashboard/v6-dashboard-html.d.ts.map +1 -1
  46. package/dist/dashboard/v6-dashboard-html.js +5 -27
  47. package/dist/dashboard/v6-dashboard-html.js.map +1 -1
  48. package/dist/dashboard/workspace-api.d.ts +10 -0
  49. package/dist/dashboard/workspace-api.d.ts.map +1 -0
  50. package/dist/dashboard/workspace-api.js +193 -0
  51. package/dist/dashboard/workspace-api.js.map +1 -0
  52. package/dist/dashboard/workspace-html.d.ts +2 -0
  53. package/dist/dashboard/workspace-html.d.ts.map +1 -0
  54. package/dist/dashboard/workspace-html.js +1555 -0
  55. package/dist/dashboard/workspace-html.js.map +1 -0
  56. package/dist/index.d.ts +8 -0
  57. package/dist/index.d.ts.map +1 -1
  58. package/dist/index.js +4 -0
  59. package/dist/index.js.map +1 -1
  60. package/dist/types.d.ts +4 -2
  61. package/dist/types.d.ts.map +1 -1
  62. package/dist/workflow-cli.d.ts +3 -0
  63. package/dist/workflow-cli.d.ts.map +1 -0
  64. package/dist/workflow-cli.js +100 -0
  65. package/dist/workflow-cli.js.map +1 -0
  66. package/docs/WORKFLOW_INTEGRATION.md +105 -0
  67. package/docs/WORKSPACE.md +70 -0
  68. package/docs/assets/context-flow-v7.2.png +0 -0
  69. package/docs/assets/workspace-graph-v7.2.png +0 -0
  70. package/docs/assets/workspace-overview-v7.2.png +0 -0
  71. package/docs/launch/RELEASE_NOTES_v7.1.0.md +32 -0
  72. package/docs/launch/RELEASE_NOTES_v7.2.0.md +24 -0
  73. package/package.json +111 -207
  74. package/skills/shadow-debug/SKILL.md +16 -0
  75. package/skills/shadow-implement/SKILL.md +16 -0
  76. package/skills/shadow-release/SKILL.md +16 -0
  77. package/skills/shadow-research/SKILL.md +12 -0
  78. package/skills/shadow-review/SKILL.md +14 -0
  79. package/skills/shadow-workflow/SKILL.md +31 -0
package/CHANGELOG.md CHANGED
@@ -1,5 +1,23 @@
1
1
  # Changelog
2
2
 
3
+ ## [7.2.0] - 2026-11-11 - Context Packs and Workspace
4
+
5
+ - Make the local workspace the default dashboard with overview, searchable memories, graph, context, and feature controls. Keep the previous dashboard at `/advanced`.
6
+ - Build size-bounded, project-scoped context packs with ranked memory selection, duplicate handling, recorded source provenance, and selection explanations.
7
+ - Use context packs for session briefings. Key cached results to the task and current settings, and check enablement before reading or returning a briefing.
8
+ - Persist four validated feature settings for context assembly, explicit cross-project context, automatic briefings, and dashboard activity delivery.
9
+ - Add `context-pack` and `features list|set` commands, read-only `context_pack` and `feature_flags` MCP tools, and public context and settings APIs.
10
+ - Refresh the README and workspace guide with a concept illustration and dashboard screenshots.
11
+
12
+ ## [7.1.0] - 2026-11-11 - Focused Workflows and Portable Skills
13
+
14
+ - Bundle six reusable skills for proportionate planning, implementation, diagnosis, review, research, and release work.
15
+ - Add project-local skill installation for Codex, Claude Code, OpenCode, DeepSeek Harness, and compatible portable clients. Preview by default; preserve user instructions, reject conflicting local edits and stale plans, validate paths, and back up managed updates.
16
+ - Add `skills list`, `skills show`, `skills targets`, `skills install`, and `workflow analyze` CLI commands.
17
+ - Add read-only `workflow_analyze` and `workflow_skills` MCP tools and public library APIs.
18
+ - Respect plan-only, diagnosis-only, and review-only scope in advisory routing. Add explicit task, mode, and complexity overrides; no provider calls or automatic task execution.
19
+ - Verify skill packaging, fresh-consumer installation, safe update behavior, and representative task scenarios.
20
+
3
21
 
4
22
  ## [7.0.0] - 2026-11-11 - Durable Memory and Explained Recall
5
23
 
package/README.md CHANGED
@@ -1,428 +1,68 @@
1
1
  # Agent Shadow Brain
2
2
 
3
- Local-first memory and coordination for AI coding agents.
3
+ Agent Shadow Brain is a shared local memory store for coding agents. Save a project's decisions, lessons, and source references in one place, then recall the useful parts when you switch tools, hand off work, or start a fresh session.
4
4
 
5
- Version: 7.0.0
5
+ ![Concept diagram showing coding agents sharing project memories and receiving a scoped, size-limited context pack](docs/assets/context-flow-v7.2.png)
6
6
 
7
+ *Concept illustration of the memory and context flow.*
7
8
 
8
- 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.
9
+ ## Get started
9
10
 
10
- 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.
11
-
12
- ## What's New in 7.0.0
13
-
14
- - **Durable multi-agent memory.** Saves lock, reload, and merge the latest store so independent agents cannot replace each other's new memories. Queued writes acknowledge success after persistence. Failed operations remain retryable and visible in storage health.
15
- - **Explainable recall.** Results include matched keywords, score components, and identities reporting the same normalized content within the same project and category. Unrelated notes no longer inflate scores. Scores are ranking heuristics, not probabilities of truth or proof of independent verification.
16
- - **Storage diagnostics.** Use `shadow-brain storage-health --json` or MCP `global_storage_health` to inspect errors and pending operations. Invalid or unsupported stores fail explicitly and remain unchanged.
17
- - **Safer setup and packaging.** Installation no longer edits agent settings. Help, version, and memory diagnostics do not load provider configuration. Dependencies are refreshed, activity-log text is escaped, and package tests install a real tarball into a fresh consumer project.
18
-
19
- ### Upgrade from 6.x
20
-
21
- Use Node.js 22.12+ within 22.x, Node 24.x, or Node 26+. Back up your existing `global.json` before upgrading and stop older Shadow Brain writers; older versions do not participate in the new lock protocol. The schema remains version 1. Start integrations explicitly using the existing setup/attach commands after installation.
22
-
23
- `writeSync()` remains an in-memory operation; call `await brain.sync()` for durable persistence. `await brain.write()` resolves after the background sync or an explicit sync; a false result means persistence failed or the queue was full. Failed accepted operations remain pending for retry. Recall reads the process snapshot, refreshed by sync; it is not an instantaneous cross-process read.
24
-
25
- ### New commands
26
-
27
- ```bash
28
- shadow-brain storage-health --json
29
- shadow-brain storage-health --db ./global.json --json
30
- shadow-brain recall-explain "deployment rollback" --limit 5
31
- shadow-brain recall-explain "database migration" --project . --min-confidence 0.4
32
- ```
33
-
34
- `storage-health` validates readability and schema, reports JSON even on failure, and exits with code 1 for an invalid store. It does not repair or rewrite an existing store; when checking a missing store it may create its parent directory. `lastSuccessfulSync` describes the current process only. The MCP health tool inspects existing process state without initializing or flushing it.
35
-
36
- The library exports `GlobalBrain`, `getGlobalBrain`, and their public types:
37
-
38
- ```js
39
- import { getGlobalBrain } from '@theihtisham/agent-shadow-brain';
40
- const brain = getGlobalBrain({ dbPath: './global.json' });
41
- await brain.init();
42
- console.log(brain.recallScored({ keywords: ['deployment'], limit: 5 }));
43
- console.log(brain.getStorageHealth());
44
- await brain.shutdown();
45
- ```
46
-
47
- Details: [release notes](docs/launch/RELEASE_NOTES_v7.0.0.md).
48
-
49
- ## Earlier dashboard features
50
-
51
- - **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.
52
- - **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.
53
- - **Realtime activity.** Memory writes, reflections, and tool events stream live over WebSocket instead of polling, with a live pulse on Home.
54
- - **Live Network.** A refreshed animation of your tools talking to the brain, with flowing signal pulses.
55
- - **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.
56
- - **Plain-language everywhere.** Cryptic feature names rewritten (e.g. Calibration → Accuracy, Pre-Mortem → Risk Check, Tokens → Cost & Usage), each with a hover description.
57
-
58
-
59
- ## What It Actually Does
60
-
61
- - Stores cross-project and cross-agent memories in a local JSON brain at `~/.shadow-brain/global.json`.
62
- - Recalls memories by project, agent, category, and keywords.
63
- - Generates source-backed resume packs for fresh sessions, account switches, context compaction, and handoffs.
64
- - Audits memory quality: source coverage, stale entries, duplicates, low-quality notes, recall health.
65
- - Creates verified memory seed drafts from dashboard/API, then requires user, agent, or dual approval before writing to durable memory.
66
- - Exports JSONL rows for evals, distillation, or local fine-tuning pipelines.
67
- - Provides CLI, dashboard API, and MCP tool surfaces.
68
- - Includes safety helpers such as hook audit, detach, and action firewall checks.
69
- - Works without telemetry and without an API key for local memory features.
70
-
71
- ## What It Does Not Claim
72
-
73
- - It does not secretly train GPT, Claude, Gemini, or any remote model.
74
- - It does not guarantee perfect recall.
75
- - It does not replace project docs, tests, source control, or human review.
76
- - It does not make every listed agent automatically available. Agent support depends on local installation and hook/config compatibility.
77
- - It does not publish or sync data unless you explicitly use export, sync, or other sharing commands.
78
-
79
- ## Install
11
+ Use Node.js 22.12+ within 22.x, Node.js 24.x, or Node.js 26+.
80
12
 
81
13
  ```bash
82
- npm install -g @theihtisham/agent-shadow-brain
14
+ npm install -g @theihtisham/agent-shadow-brain@7.2.0
15
+ shadow-brain dash . --no-analysis
83
16
  ```
84
17
 
85
- CLI binaries:
18
+ Run the dashboard command from your project directory. It opens the local workspace and skips background project analysis. Open the printed address if the browser does not start automatically. Use a second terminal for other commands while the dashboard is running.
86
19
 
87
- ```bash
88
- shadow-brain --help
89
- asb --help
90
- ```
20
+ ## Explore your memory
91
21
 
92
- You can also run without global install:
22
+ Version 7.2 opens a five-view workspace that runs locally and works offline.
93
23
 
94
- ```bash
95
- npx @theihtisham/agent-shadow-brain@latest --help
96
- ```
24
+ - **Overview** shows memory and project counts, recent memories, and activity.
25
+ - **Memories** lets you search and filter saved entries by project, category, and agent.
26
+ - **Graph** shows which project each memory belongs to and which agent recorded it. Select a node to inspect it.
27
+ - **Context** builds a copyable pack for a project and task, with selection reasons and recorded sources.
28
+ - **Features** controls context packs, cross-project context, automatic briefings, and the dashboard activity feed.
97
29
 
98
- ## Safe First Run
30
+ ![Workspace overview with memory counts, projects, recent memories, and activity](docs/assets/workspace-overview-v7.2.png)
99
31
 
100
- Start by auditing before attaching hooks:
32
+ ![Workspace graph with project clusters, memory nodes, and a detail panel](docs/assets/workspace-graph-v7.2.png)
101
33
 
102
- ```bash
103
- shadow-brain audit-hooks .
104
- shadow-brain live-brain status .
105
- ```
34
+ *Screenshots from a running workspace populated with synthetic memories.*
106
35
 
107
- Only attach after you review what will be changed:
36
+ Open **Advanced tools** or visit `/advanced` for the previous dashboard. [Workspace guide](docs/WORKSPACE.md)
108
37
 
109
- ```bash
110
- shadow-brain attach-all .
111
- ```
112
-
113
- Detach later if needed:
38
+ ## Build a context pack
114
39
 
115
40
  ```bash
116
- shadow-brain detach-all .
41
+ shadow-brain context-pack "import retry behavior" --project . --token-budget 1200
42
+ shadow-brain features list
43
+ shadow-brain features set automaticBriefing off
117
44
  ```
118
45
 
119
- ## v6.0.3: Live Brain
120
-
121
- The 6.0.3 release focuses on practical long-memory improvement for agents.
122
-
123
- ### Live Brain Status
124
-
125
- ```bash
126
- shadow-brain live-brain status .
127
- ```
128
-
129
- Shows:
130
-
131
- - memory count
132
- - average memory quality
133
- - source coverage
134
- - stale memories
135
- - duplicate clusters
136
- - recall eval score
137
- - recommended cleanup actions
138
-
139
- JSON output:
140
-
141
- ```bash
142
- shadow-brain live-brain status . --json
143
- ```
46
+ A pack starts with the selected project's memories, collapses exact duplicates, and fits the rendered text to a size budget. Add `--json` to see why entries were selected or skipped. Cross-project context requires both an enabled feature setting and an explicit request. Token counts are estimates.
144
47
 
145
- ### Agent Briefing
48
+ Automatic briefings use the same context selection. Cached briefings follow the current task and feature settings, so disabling briefings takes effect on the next request.
146
49
 
147
- Generate a markdown briefing for a fresh agent session:
148
-
149
- ```bash
150
- shadow-brain live-brain brief . -o SHADOW_BRAIN_AGENT_BRIEF.md
151
- ```
152
-
153
- The briefing includes:
154
-
155
- - rules for agents
156
- - top source-backed memories
157
- - memory warnings
158
- - recall health
159
- - commands agents should run next
160
-
161
- ### Recall Eval
162
-
163
- Check whether the brain can retrieve useful memories for common agent tasks:
164
-
165
- ```bash
166
- shadow-brain live-brain eval .
167
- ```
168
-
169
- Custom eval queries use pipe separators:
170
-
171
- ```bash
172
- shadow-brain live-brain eval . --queries "current blocker|do not repeat|verified command"
173
- ```
174
-
175
- ### Memory Hygiene
176
-
177
- List concrete cleanup and learning actions:
178
-
179
- ```bash
180
- shadow-brain live-brain hygiene .
181
- ```
182
-
183
- This highlights missing sources, stale memories, duplicates, weak recall, and missing project-scoped memories.
184
-
185
- ### Training/Eval Export
186
-
187
- Export source-backed memories as JSONL:
188
-
189
- ```bash
190
- shadow-brain live-brain train-pack . --out shadow-brain-training.jsonl
191
- ```
192
-
193
- This is useful for:
194
-
195
- - retrieval evals
196
- - local distillation experiments
197
- - supervised fine-tuning datasets
198
- - memory regression tests
199
-
200
- The export is only data preparation. You choose the downstream training/eval tool.
201
-
202
- ## Core Memory Commands
203
-
204
- Recall from the global brain:
205
-
206
- ```bash
207
- shadow-brain global recall --query "current blocker next step" --json --limit 8
208
- ```
209
-
210
- Show global stats:
211
-
212
- ```bash
213
- shadow-brain global stats
214
- ```
215
-
216
- Create a source-backed resume seed:
217
-
218
- ```bash
219
- shadow-brain resume-seed . -o SHADOW_BRAIN_RESUME_SEED.md
220
- ```
50
+ ## Add skills to a project
221
51
 
222
- Show what a project has learned:
52
+ Six bundled skills cover workflow selection, implementation, debugging, review, research, and release. They help a client focus on the requested work, plan when useful, and verify the result.
223
53
 
224
54
  ```bash
225
- shadow-brain timeline . --limit 30
226
- ```
227
-
228
- Create a cross-agent handoff packet:
229
-
230
- ```bash
231
- shadow-brain handoff codex claude-code . --task "continue release verification"
232
- ```
233
-
234
- Record a durable memory from a script:
235
-
236
- ```bash
237
- node tools/record-global-memory.mjs ^
238
- --project-dir "." ^
239
- --project-name "my-project" ^
240
- --agent codex ^
241
- --category "project.lesson" ^
242
- --importance 0.8 ^
243
- --tags "memory,release" ^
244
- --sources "README.md,CHANGELOG.md" ^
245
- --content "Keep release notes source-backed and verify npm metadata before publish."
246
- ```
247
-
248
- ## Dashboard
249
-
250
- Start the local dashboard:
251
-
252
- ```bash
253
- shadow-brain dash . --no-open --port 7341
254
- ```
255
-
256
- For a fast UI/API-only launch on a large repo:
257
-
258
- ```bash
259
- shadow-brain dash . --no-open --no-analysis --host 127.0.0.1 --port 7341
260
- ```
261
-
262
- Open:
263
-
264
- ```text
265
- http://127.0.0.1:7341
266
- ```
267
-
268
- The v6 dashboard includes a **Live Brain** tab for memory health, source coverage, recall evals, hygiene actions, top memories, and the generated agent briefing.
269
-
270
- It also includes:
271
-
272
- - **Memory Browser intelligence cards** for total memories, source coverage, fresh learning, seed queue, top categories, agent coverage, and top tags.
273
- - **Memory Seeder** for controlled research-to-memory workflows. Drafts stay out of the global brain until approval is complete.
274
- - **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.
275
-
276
- ### Realtime Activity (new in 6.1.0)
277
-
278
- 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.
279
-
280
- - **Live Pulse** card on the Overview with a streaming mini-feed and an events/min rate.
281
- - **Activity Log** tab with filter chips, a pulsing LIVE badge, pause/resume, clear, search, and an events/min sparkline.
282
- - **Connection indicator** in the header — green when the realtime socket is live, amber while reconnecting.
283
- - **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.
284
-
285
- Polling remains as a 15-second reconciliation fallback; live events arrive in well under a second.
286
-
287
- ### Intelligence Hub — Memory Constellation (new in 6.2.0)
288
-
289
- 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.
290
-
291
- - **Interactive**: scroll to zoom, drag to pan, click a node to focus its neighborhood and open a detail drawer; hover for a tooltip.
292
- - **Filters + search** by node type (memory / project / agent / tag).
293
- - **Live**: new memories pulse into the graph over the realtime stream.
294
- - **Analytics strip**: source-coverage gauge, agent-contribution and category charts, tag cloud, and a recent-memory feed.
295
- - Works instantly on your existing `~/.shadow-brain/global.json` — no project analysis or setup step.
296
-
297
- 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).
298
-
299
- Constellation API:
300
-
301
- ```text
302
- GET /api/v6/memory-graph
303
- ```
304
-
305
-
306
- Memory seeding API:
307
-
308
- ```text
309
- GET /api/v6/seed-drafts
310
- POST /api/v6/seed-draft
311
- POST /api/v6/seed-approve
312
- POST /api/v6/seed-reject
313
- POST /api/v6/seed-commit
314
- GET /api/v6/memory-intelligence
315
- ```
316
-
317
- Useful API endpoints:
318
-
319
- ```text
320
- GET/POST /api/v6/live-brain
321
- GET/POST /api/v6/resume-pack
322
- GET/POST /api/v6/ww2br-recall
323
- GET/POST /api/v6/memory-browser
324
- ```
325
-
326
- Example:
327
-
328
- ```bash
329
- curl "http://127.0.0.1:7341/api/v6/live-brain?projectDir=C:/path/to/project"
330
- ```
331
-
332
- ## MCP Tools
333
-
334
- The MCP server exposes memory and agent-control tools for compatible clients.
335
-
336
- New in 6.3.0:
337
-
338
- - `global_recall_scored` — recall with a per-memory confidence score (recency, author importance, cross-agent corroboration, prior usage, keyword relevance). Results are ranked by confidence so agents can weight memories instead of trusting every hit equally. Supports `minConfidence` to drop low-trust hits.
339
-
340
- New in 6.0.3:
341
-
342
- - `live_brain_status`
343
- - `live_brain_brief`
344
- - `live_brain_train_pack`
345
-
346
- Existing useful tools include:
347
-
348
- - `global_recall`
349
- - `global_recall_scored`
350
- - `global_stats`
351
- - `global_timeline`
352
- - `subconscious_inject`
353
- - `agent_handoff`
354
- - `firewall_check`
355
-
356
- Start MCP from the dashboard API or existing CLI/server integration, depending on your setup.
357
-
358
- ## How Agents Should Use It
359
-
360
- Recommended workflow for complex work:
361
-
362
- 1. Run `shadow-brain live-brain status <project>`.
363
- 2. Generate or read a live briefing.
364
- 3. Verify current project docs and source files.
365
- 4. Work normally.
366
- 5. Record only durable, source-backed lessons after proof.
367
- 6. Run recall evals when memory quality starts to drift.
368
-
369
- Good memories are short, action-oriented, and source-backed:
370
-
371
- ```text
372
- [lesson:release-readme-v1] Before publishing, verify package.json version, package-lock root version, README install commands, build output, and npm pack contents.
373
- Sources: package.json; package-lock.json; README.md
374
- Tags: release,npm,verification
375
- ```
376
-
377
- Bad memories are vague:
378
-
379
- ```text
380
- Make project better.
381
- ```
382
-
383
- ## Local Data
384
-
385
- Default global brain:
386
-
387
- ```text
388
- ~/.shadow-brain/global.json
389
- ```
390
-
391
- Project-local generated files may include:
392
-
393
- ```text
394
- SHADOW_BRAIN_AGENT_BRIEF.md
395
- SHADOW_BRAIN_RESUME_SEED.md
396
- shadow-brain-training.jsonl
397
- ```
398
-
399
- Do not store secrets, API keys, passwords, private keys, or raw credentials in memory content, metadata, tags, prompts, reports, or exported training data.
400
-
401
- ## Development
402
-
403
- ```bash
404
- npm ci --ignore-scripts
405
- npm run verify
406
- npm run test:package
407
- ```
408
-
409
- Focused tests:
410
-
411
- ```bash
412
- npx vitest run tests/brain/live-brain.test.ts tests/brain/context-continuity.test.ts
413
- ```
414
-
415
- On Windows PowerShell, if execution policy blocks `npm.ps1`, use:
416
-
417
- ```powershell
418
- npm.cmd run build
419
- npx.cmd vitest run tests\brain\live-brain.test.ts
55
+ shadow-brain skills list
56
+ shadow-brain skills install . --target codex
57
+ shadow-brain skills install . --target codex --apply
420
58
  ```
421
59
 
422
- ## Release Checklist
60
+ The first install command previews the files. The second applies the install and preserves your existing project instructions. Choose `claude-code`, `opencode`, `deepseek-harness`, or `portable` for other clients. Discovery depends on each client's skill support. [Skill integration guide](docs/WORKFLOW_INTEGRATION.md)
423
61
 
424
- Run `npm run verify`, `npm audit --audit-level=high`, and `npm run test:package`. Inspect the package allowlist, then publish the verified tarball. Confirm the npm version, integrity, and GitHub tag before announcing a release. See [the complete release checklist](docs/launch/RELEASE_CHECKLIST_v7.0.0.md).
62
+ ## Upgrade and reference
425
63
 
426
- ## License
64
+ If you are upgrading from 6.x, back up `~/.shadow-brain/global.json` and stop older writers before using 7.x. The 7.x writers use a new lock protocol and keep memory schema version 1. [7.0 migration notes](docs/launch/RELEASE_NOTES_v7.0.0.md)
427
65
 
428
- MIT
66
+ - [7.2 release notes](docs/launch/RELEASE_NOTES_v7.2.0.md)
67
+ - [Earlier CLI, MCP, seeding, and export guide](https://github.com/ihtishaam-dev/agent-shadow-brain/blob/v7.1.0/README.md)
68
+ - [Changelog](CHANGELOG.md) · [MIT license](LICENSE)
@@ -1,6 +1,6 @@
1
1
  // src/brain/auto-update.ts — Check for Shadow Brain updates
2
2
  import * as https from 'https';
3
- const CURRENT_VERSION = '7.0.0';
3
+ const CURRENT_VERSION = '7.2.0';
4
4
  const PACKAGE_NAME = '@theihtisham/agent-shadow-brain';
5
5
  export async function checkForUpdate() {
6
6
  return new Promise((resolve) => {
@@ -35,7 +35,7 @@ export class BrainPortability {
35
35
  const fileName = `brain-${projectName}-${timestamp}.json`;
36
36
  const filePath = path.join(this.exportDir, fileName);
37
37
  const data = {
38
- version: '6.0.3',
38
+ version: '7.2.0',
39
39
  exportedAt: new Date(),
40
40
  projectName,
41
41
  projectDir: this.projectDir,
@@ -0,0 +1,58 @@
1
+ import { type GlobalBrain } from './global-brain.js';
2
+ import { type FeatureFlags } from './feature-settings.js';
3
+ import type { AgentTool } from '../types.js';
4
+ export interface ContextAssemblyOptions {
5
+ projectId: string;
6
+ query?: string;
7
+ maxEntries?: number;
8
+ tokenBudget?: number;
9
+ maxChars?: number;
10
+ includeCrossProject?: boolean;
11
+ features?: Pick<FeatureFlags, 'contextAssembly' | 'crossProjectContext'>;
12
+ minImportance?: number;
13
+ lookbackHours?: number;
14
+ alwaysInclude?: readonly string[];
15
+ }
16
+ export interface ContextPackEntry {
17
+ id: string;
18
+ projectId: string;
19
+ projectName: string;
20
+ agentTool: AgentTool;
21
+ category: string;
22
+ excerpt: string;
23
+ excerptTruncated: boolean;
24
+ score: number;
25
+ createdAt: string | null;
26
+ matchedKeywords: string[];
27
+ sources: string[];
28
+ sourceReferences: Array<{
29
+ source: string;
30
+ memoryId: string;
31
+ }>;
32
+ duplicateIds: string[];
33
+ reasons: string[];
34
+ }
35
+ export interface ContextPack {
36
+ enabled: boolean;
37
+ projectId: string;
38
+ scope: 'project' | 'cross-project';
39
+ queryKeywords: string[];
40
+ entries: ContextPackEntry[];
41
+ excluded: Array<{
42
+ id: string;
43
+ reason: 'duplicate' | 'budget' | 'limit' | 'empty' | 'lookback';
44
+ }>;
45
+ budget: {
46
+ tokenBudget: number;
47
+ maxChars: number;
48
+ usedChars: number;
49
+ estimatedTokens: number;
50
+ };
51
+ warnings: string[];
52
+ markdown: string;
53
+ }
54
+ /** Share query cleanup with explained recall and limit the number of searched terms. */
55
+ export declare function contextQueryKeywords(query: string | undefined): string[];
56
+ /** Assemble bounded reference context from explained recall without reading files or writing memories. */
57
+ export declare function assembleContext(brain: Pick<GlobalBrain, 'recallScored'>, options: ContextAssemblyOptions): ContextPack;
58
+ //# sourceMappingURL=context-assembly.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"context-assembly.d.ts","sourceRoot":"","sources":["../../src/brain/context-assembly.ts"],"names":[],"mappings":"AAAA,OAAO,EAA2B,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC9E,OAAO,EAAyB,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACjF,OAAO,KAAK,EAAE,SAAS,EAAqB,MAAM,aAAa,CAAC;AAEhE,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,iBAAiB,GAAG,qBAAqB,CAAC,CAAC;IACzE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,SAAS,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,gBAAgB,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC9D,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,SAAS,GAAG,eAAe,CAAC;IACnC,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,QAAQ,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,UAAU,CAAA;KAAE,CAAC,CAAC;IACjG,MAAM,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9F,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAiCD,wFAAwF;AACxF,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAKxE;AA+DD,0GAA0G;AAC1G,wBAAgB,eAAe,CAAC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,cAAc,CAAC,EAAE,OAAO,EAAE,sBAAsB,GAAG,WAAW,CAqGtH"}