@theihtisham/agent-shadow-brain 7.1.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 (59) hide show
  1. package/CHANGELOG.md +9 -0
  2. package/README.md +36 -418
  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 +2 -0
  18. package/dist/brain/mcp-server.d.ts.map +1 -1
  19. package/dist/brain/mcp-server.js +47 -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/cli.js +4 -2
  27. package/dist/cli.js.map +1 -1
  28. package/dist/context-cli.d.ts +3 -0
  29. package/dist/context-cli.d.ts.map +1 -0
  30. package/dist/context-cli.js +54 -0
  31. package/dist/context-cli.js.map +1 -0
  32. package/dist/dashboard/server.d.ts +1 -0
  33. package/dist/dashboard/server.d.ts.map +1 -1
  34. package/dist/dashboard/server.js +32 -4
  35. package/dist/dashboard/server.js.map +1 -1
  36. package/dist/dashboard/v6-dashboard-html.d.ts +1 -1
  37. package/dist/dashboard/v6-dashboard-html.d.ts.map +1 -1
  38. package/dist/dashboard/v6-dashboard-html.js +5 -27
  39. package/dist/dashboard/v6-dashboard-html.js.map +1 -1
  40. package/dist/dashboard/workspace-api.d.ts +10 -0
  41. package/dist/dashboard/workspace-api.d.ts.map +1 -0
  42. package/dist/dashboard/workspace-api.js +193 -0
  43. package/dist/dashboard/workspace-api.js.map +1 -0
  44. package/dist/dashboard/workspace-html.d.ts +2 -0
  45. package/dist/dashboard/workspace-html.d.ts.map +1 -0
  46. package/dist/dashboard/workspace-html.js +1555 -0
  47. package/dist/dashboard/workspace-html.js.map +1 -0
  48. package/dist/index.d.ts +4 -0
  49. package/dist/index.d.ts.map +1 -1
  50. package/dist/index.js +2 -0
  51. package/dist/index.js.map +1 -1
  52. package/dist/types.d.ts +4 -2
  53. package/dist/types.d.ts.map +1 -1
  54. package/docs/WORKSPACE.md +70 -0
  55. package/docs/assets/context-flow-v7.2.png +0 -0
  56. package/docs/assets/workspace-graph-v7.2.png +0 -0
  57. package/docs/assets/workspace-overview-v7.2.png +0 -0
  58. package/docs/launch/RELEASE_NOTES_v7.2.0.md +24 -0
  59. package/package.json +19 -121
package/CHANGELOG.md CHANGED
@@ -1,5 +1,14 @@
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
+
3
12
  ## [7.1.0] - 2026-11-11 - Focused Workflows and Portable Skills
4
13
 
5
14
  - Bundle six reusable skills for proportionate planning, implementation, diagnosis, review, research, and release work.
package/README.md CHANGED
@@ -1,450 +1,68 @@
1
1
  # Agent Shadow Brain
2
2
 
3
- Local-first memory, focused task workflows, and portable skills 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.1.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.1.0
13
-
14
- Six built-in skills help an agent understand the request, plan in proportion to the work, carry out authorized changes, and verify the result. Simple answers stay simple. Planning-only, diagnosis-only, and review-only requests keep their boundaries; existing authorization carries forward.
15
-
16
- - **Focused skills:** `shadow-workflow`, `shadow-implement`, `shadow-debug`, `shadow-review`, `shadow-research`, and `shadow-release`.
17
- - **Project integrations:** Codex, Claude Code, OpenCode, and DeepSeek Harness skill directories, plus a portable option. Preview installation first; preserve existing project instructions and locally edited skills.
18
- - **Workflow guidance:** CLI, library, and MCP interfaces suggest steps and relevant skills. Routing is a local English-language heuristic with explicit overrides. The host agent interprets the request and performs the work.
19
- - **No provider setup required:** skills and workflow analysis run locally without model calls, credentials, background agents, or global configuration changes.
20
-
21
- Run these commands **from your project root**:
22
-
23
- ```bash
24
- shadow-brain skills list
25
- shadow-brain skills install . --target codex
26
- shadow-brain skills install . --target codex --apply
27
- shadow-brain workflow analyze "Investigate and fix the failing export" --json
28
- ```
29
-
30
- Replace `codex` with `claude-code`, `opencode`, `deepseek-harness`, or `portable`. Use `--target all` to install the four native layouts. The preview writes nothing; `--apply` writes the listed files after validation. Clients must support and enable skill discovery. DeepSeek Harness requires its filesystem skills, registry/tool support, and project-instruction context to be enabled. Installing files alone does not prove a running client loaded them.
31
-
32
- See the [integration guide](docs/WORKFLOW_INTEGRATION.md) for selection, preservation behavior, library/MCP examples, and compatibility sources; [7.1 release notes](docs/launch/RELEASE_NOTES_v7.1.0.md) describe the scope.
33
-
34
- ## Memory improvements in 7.0.0
35
-
36
- - **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.
37
- - **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.
38
- - **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.
39
- - **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.
40
-
41
- ### Upgrade from 6.x
42
-
43
- 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.
44
-
45
- `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.
46
-
47
- ### New commands
48
-
49
- ```bash
50
- shadow-brain storage-health --json
51
- shadow-brain storage-health --db ./global.json --json
52
- shadow-brain recall-explain "deployment rollback" --limit 5
53
- shadow-brain recall-explain "database migration" --project . --min-confidence 0.4
54
- ```
55
-
56
- `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.
57
-
58
- The library exports `GlobalBrain`, `getGlobalBrain`, and their public types:
59
-
60
- ```js
61
- import { getGlobalBrain } from '@theihtisham/agent-shadow-brain';
62
- const brain = getGlobalBrain({ dbPath: './global.json' });
63
- await brain.init();
64
- console.log(brain.recallScored({ keywords: ['deployment'], limit: 5 }));
65
- console.log(brain.getStorageHealth());
66
- await brain.shutdown();
67
- ```
68
-
69
- Details: [release notes](docs/launch/RELEASE_NOTES_v7.0.0.md).
70
-
71
- ## Earlier dashboard features
72
-
73
- - **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.
74
- - **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.
75
- - **Realtime activity.** Memory writes, reflections, and tool events stream live over WebSocket instead of polling, with a live pulse on Home.
76
- - **Live Network.** A refreshed animation of your tools talking to the brain, with flowing signal pulses.
77
- - **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.
78
- - **Plain-language everywhere.** Cryptic feature names rewritten (e.g. Calibration → Accuracy, Pre-Mortem → Risk Check, Tokens → Cost & Usage), each with a hover description.
79
-
80
-
81
- ## What It Actually Does
82
-
83
- - Stores cross-project and cross-agent memories in a local JSON brain at `~/.shadow-brain/global.json`.
84
- - Recalls memories by project, agent, category, and keywords.
85
- - Generates source-backed resume packs for fresh sessions, account switches, context compaction, and handoffs.
86
- - Audits memory quality: source coverage, stale entries, duplicates, low-quality notes, recall health.
87
- - Creates verified memory seed drafts from dashboard/API, then requires user, agent, or dual approval before writing to durable memory.
88
- - Exports JSONL rows for evals, distillation, or local fine-tuning pipelines.
89
- - Provides CLI, dashboard API, and MCP tool surfaces.
90
- - Includes safety helpers such as hook audit, detach, and action firewall checks.
91
- - Works without telemetry and without an API key for local memory features.
92
-
93
- ## What It Does Not Claim
94
-
95
- - It does not secretly train GPT, Claude, Gemini, or any remote model.
96
- - It does not guarantee perfect recall.
97
- - It does not replace project docs, tests, source control, or human review.
98
- - It does not make every listed agent automatically available. Agent support depends on local installation and hook/config compatibility.
99
- - It does not publish or sync data unless you explicitly use export, sync, or other sharing commands.
100
-
101
- ## Install
102
-
103
- ```bash
104
- npm install -g @theihtisham/agent-shadow-brain
105
- ```
106
-
107
- CLI binaries:
108
-
109
- ```bash
110
- shadow-brain --help
111
- asb --help
112
- ```
113
-
114
- You can also run without global install:
115
-
116
- ```bash
117
- npx @theihtisham/agent-shadow-brain@latest --help
118
- ```
119
-
120
- ## Safe First Run
121
-
122
- Start by auditing before attaching hooks:
123
-
124
- ```bash
125
- shadow-brain audit-hooks .
126
- shadow-brain live-brain status .
127
- ```
128
-
129
- Only attach after you review what will be changed:
130
-
131
- ```bash
132
- shadow-brain attach-all .
133
- ```
134
-
135
- Detach later if needed:
136
-
137
- ```bash
138
- shadow-brain detach-all .
139
- ```
140
-
141
- ## v6.0.3: Live Brain
142
-
143
- The 6.0.3 release focuses on practical long-memory improvement for agents.
144
-
145
- ### Live Brain Status
146
-
147
- ```bash
148
- shadow-brain live-brain status .
149
- ```
150
-
151
- Shows:
152
-
153
- - memory count
154
- - average memory quality
155
- - source coverage
156
- - stale memories
157
- - duplicate clusters
158
- - recall eval score
159
- - recommended cleanup actions
160
-
161
- JSON output:
162
-
163
- ```bash
164
- shadow-brain live-brain status . --json
165
- ```
166
-
167
- ### Agent Briefing
168
-
169
- Generate a markdown briefing for a fresh agent session:
170
-
171
- ```bash
172
- shadow-brain live-brain brief . -o SHADOW_BRAIN_AGENT_BRIEF.md
173
- ```
174
-
175
- The briefing includes:
176
-
177
- - rules for agents
178
- - top source-backed memories
179
- - memory warnings
180
- - recall health
181
- - commands agents should run next
182
-
183
- ### Recall Eval
184
-
185
- Check whether the brain can retrieve useful memories for common agent tasks:
186
-
187
- ```bash
188
- shadow-brain live-brain eval .
189
- ```
190
-
191
- Custom eval queries use pipe separators:
192
-
193
- ```bash
194
- shadow-brain live-brain eval . --queries "current blocker|do not repeat|verified command"
195
- ```
196
-
197
- ### Memory Hygiene
198
-
199
- List concrete cleanup and learning actions:
200
-
201
- ```bash
202
- shadow-brain live-brain hygiene .
203
- ```
204
-
205
- This highlights missing sources, stale memories, duplicates, weak recall, and missing project-scoped memories.
206
-
207
- ### Training/Eval Export
208
-
209
- Export source-backed memories as JSONL:
210
-
211
- ```bash
212
- shadow-brain live-brain train-pack . --out shadow-brain-training.jsonl
213
- ```
214
-
215
- This is useful for:
216
-
217
- - retrieval evals
218
- - local distillation experiments
219
- - supervised fine-tuning datasets
220
- - memory regression tests
221
-
222
- The export is only data preparation. You choose the downstream training/eval tool.
223
-
224
- ## Core Memory Commands
225
-
226
- Recall from the global brain:
11
+ Use Node.js 22.12+ within 22.x, Node.js 24.x, or Node.js 26+.
227
12
 
228
13
  ```bash
229
- shadow-brain global recall --query "current blocker next step" --json --limit 8
14
+ npm install -g @theihtisham/agent-shadow-brain@7.2.0
15
+ shadow-brain dash . --no-analysis
230
16
  ```
231
17
 
232
- Show global stats:
233
-
234
- ```bash
235
- shadow-brain global stats
236
- ```
237
-
238
- Create a source-backed resume seed:
239
-
240
- ```bash
241
- shadow-brain resume-seed . -o SHADOW_BRAIN_RESUME_SEED.md
242
- ```
243
-
244
- Show what a project has learned:
245
-
246
- ```bash
247
- shadow-brain timeline . --limit 30
248
- ```
249
-
250
- Create a cross-agent handoff packet:
251
-
252
- ```bash
253
- shadow-brain handoff codex claude-code . --task "continue release verification"
254
- ```
255
-
256
- Record a durable memory from a script:
257
-
258
- ```bash
259
- node tools/record-global-memory.mjs ^
260
- --project-dir "." ^
261
- --project-name "my-project" ^
262
- --agent codex ^
263
- --category "project.lesson" ^
264
- --importance 0.8 ^
265
- --tags "memory,release" ^
266
- --sources "README.md,CHANGELOG.md" ^
267
- --content "Keep release notes source-backed and verify npm metadata before publish."
268
- ```
269
-
270
- ## Dashboard
271
-
272
- Start the local dashboard:
273
-
274
- ```bash
275
- shadow-brain dash . --no-open --port 7341
276
- ```
277
-
278
- For a fast UI/API-only launch on a large repo:
279
-
280
- ```bash
281
- shadow-brain dash . --no-open --no-analysis --host 127.0.0.1 --port 7341
282
- ```
283
-
284
- Open:
285
-
286
- ```text
287
- http://127.0.0.1:7341
288
- ```
289
-
290
- The v6 dashboard includes a **Live Brain** tab for memory health, source coverage, recall evals, hygiene actions, top memories, and the generated agent briefing.
291
-
292
- It also includes:
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.
293
19
 
294
- - **Memory Browser intelligence cards** for total memories, source coverage, fresh learning, seed queue, top categories, agent coverage, and top tags.
295
- - **Memory Seeder** for controlled research-to-memory workflows. Drafts stay out of the global brain until approval is complete.
296
- - **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.
20
+ ## Explore your memory
297
21
 
298
- ### Realtime Activity (new in 6.1.0)
22
+ Version 7.2 opens a five-view workspace that runs locally and works offline.
299
23
 
300
- 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.
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.
301
29
 
302
- - **Live Pulse** card on the Overview with a streaming mini-feed and an events/min rate.
303
- - **Activity Log** tab with filter chips, a pulsing LIVE badge, pause/resume, clear, search, and an events/min sparkline.
304
- - **Connection indicator** in the header — green when the realtime socket is live, amber while reconnecting.
305
- - **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.
30
+ ![Workspace overview with memory counts, projects, recent memories, and activity](docs/assets/workspace-overview-v7.2.png)
306
31
 
307
- Polling remains as a 15-second reconciliation fallback; live events arrive in well under a second.
32
+ ![Workspace graph with project clusters, memory nodes, and a detail panel](docs/assets/workspace-graph-v7.2.png)
308
33
 
309
- ### Intelligence Hub — Memory Constellation (new in 6.2.0)
34
+ *Screenshots from a running workspace populated with synthetic memories.*
310
35
 
311
- 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.
36
+ Open **Advanced tools** or visit `/advanced` for the previous dashboard. [Workspace guide](docs/WORKSPACE.md)
312
37
 
313
- - **Interactive**: scroll to zoom, drag to pan, click a node to focus its neighborhood and open a detail drawer; hover for a tooltip.
314
- - **Filters + search** by node type (memory / project / agent / tag).
315
- - **Live**: new memories pulse into the graph over the realtime stream.
316
- - **Analytics strip**: source-coverage gauge, agent-contribution and category charts, tag cloud, and a recent-memory feed.
317
- - Works instantly on your existing `~/.shadow-brain/global.json` — no project analysis or setup step.
318
-
319
- 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).
320
-
321
- Constellation API:
322
-
323
- ```text
324
- GET /api/v6/memory-graph
325
- ```
326
-
327
-
328
- Memory seeding API:
329
-
330
- ```text
331
- GET /api/v6/seed-drafts
332
- POST /api/v6/seed-draft
333
- POST /api/v6/seed-approve
334
- POST /api/v6/seed-reject
335
- POST /api/v6/seed-commit
336
- GET /api/v6/memory-intelligence
337
- ```
338
-
339
- Useful API endpoints:
340
-
341
- ```text
342
- GET/POST /api/v6/live-brain
343
- GET/POST /api/v6/resume-pack
344
- GET/POST /api/v6/ww2br-recall
345
- GET/POST /api/v6/memory-browser
346
- ```
347
-
348
- Example:
38
+ ## Build a context pack
349
39
 
350
40
  ```bash
351
- curl "http://127.0.0.1:7341/api/v6/live-brain?projectDir=C:/path/to/project"
41
+ shadow-brain context-pack "import retry behavior" --project . --token-budget 1200
42
+ shadow-brain features list
43
+ shadow-brain features set automaticBriefing off
352
44
  ```
353
45
 
354
- ## MCP Tools
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.
355
47
 
356
- The MCP server exposes memory and agent-control tools for compatible clients.
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.
357
49
 
358
- New in 6.3.0:
50
+ ## Add skills to a project
359
51
 
360
- - `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.
361
-
362
- New in 6.0.3:
363
-
364
- - `live_brain_status`
365
- - `live_brain_brief`
366
- - `live_brain_train_pack`
367
-
368
- Existing useful tools include:
369
-
370
- - `global_recall`
371
- - `global_recall_scored`
372
- - `global_stats`
373
- - `global_timeline`
374
- - `subconscious_inject`
375
- - `agent_handoff`
376
- - `firewall_check`
377
-
378
- Start MCP from the dashboard API or existing CLI/server integration, depending on your setup.
379
-
380
- ## How Agents Should Use It
381
-
382
- Recommended workflow for complex work:
383
-
384
- 1. Run `shadow-brain live-brain status <project>`.
385
- 2. Generate or read a live briefing.
386
- 3. Verify current project docs and source files.
387
- 4. Work normally.
388
- 5. Record only durable, source-backed lessons after proof.
389
- 6. Run recall evals when memory quality starts to drift.
390
-
391
- Good memories are short, action-oriented, and source-backed:
392
-
393
- ```text
394
- [lesson:release-readme-v1] Before publishing, verify package.json version, package-lock root version, README install commands, build output, and npm pack contents.
395
- Sources: package.json; package-lock.json; README.md
396
- Tags: release,npm,verification
397
- ```
398
-
399
- Bad memories are vague:
400
-
401
- ```text
402
- Make project better.
403
- ```
404
-
405
- ## Local Data
406
-
407
- Default global brain:
408
-
409
- ```text
410
- ~/.shadow-brain/global.json
411
- ```
412
-
413
- Project-local generated files may include:
414
-
415
- ```text
416
- SHADOW_BRAIN_AGENT_BRIEF.md
417
- SHADOW_BRAIN_RESUME_SEED.md
418
- shadow-brain-training.jsonl
419
- ```
420
-
421
- Do not store secrets, API keys, passwords, private keys, or raw credentials in memory content, metadata, tags, prompts, reports, or exported training data.
422
-
423
- ## Development
424
-
425
- ```bash
426
- npm ci --ignore-scripts
427
- npm run verify
428
- npm run test:package
429
- ```
430
-
431
- Focused tests:
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.
432
53
 
433
54
  ```bash
434
- npx vitest run tests/brain/live-brain.test.ts tests/brain/context-continuity.test.ts
435
- ```
436
-
437
- On Windows PowerShell, if execution policy blocks `npm.ps1`, use:
438
-
439
- ```powershell
440
- npm.cmd run build
441
- 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
442
58
  ```
443
59
 
444
- ## 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)
445
61
 
446
- 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
447
63
 
448
- ## 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)
449
65
 
450
- 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.1.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: '7.1.0',
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"}