@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.
- package/CHANGELOG.md +9 -0
- package/README.md +36 -418
- package/dist/brain/auto-update.js +1 -1
- package/dist/brain/brain-portability.js +1 -1
- package/dist/brain/context-assembly.d.ts +58 -0
- package/dist/brain/context-assembly.d.ts.map +1 -0
- package/dist/brain/context-assembly.js +207 -0
- package/dist/brain/context-assembly.js.map +1 -0
- package/dist/brain/feature-settings.d.ts +53 -0
- package/dist/brain/feature-settings.d.ts.map +1 -0
- package/dist/brain/feature-settings.js +232 -0
- package/dist/brain/feature-settings.js.map +1 -0
- package/dist/brain/global-brain.d.ts +1 -0
- package/dist/brain/global-brain.d.ts.map +1 -1
- package/dist/brain/global-brain.js +3 -3
- package/dist/brain/global-brain.js.map +1 -1
- package/dist/brain/mcp-server.d.ts +2 -0
- package/dist/brain/mcp-server.d.ts.map +1 -1
- package/dist/brain/mcp-server.js +47 -5
- package/dist/brain/mcp-server.js.map +1 -1
- package/dist/brain/orchestrator.js +1 -1
- package/dist/brain/subconscious.d.ts +19 -24
- package/dist/brain/subconscious.d.ts.map +1 -1
- package/dist/brain/subconscious.js +77 -218
- package/dist/brain/subconscious.js.map +1 -1
- package/dist/cli.js +4 -2
- package/dist/cli.js.map +1 -1
- package/dist/context-cli.d.ts +3 -0
- package/dist/context-cli.d.ts.map +1 -0
- package/dist/context-cli.js +54 -0
- package/dist/context-cli.js.map +1 -0
- package/dist/dashboard/server.d.ts +1 -0
- package/dist/dashboard/server.d.ts.map +1 -1
- package/dist/dashboard/server.js +32 -4
- package/dist/dashboard/server.js.map +1 -1
- package/dist/dashboard/v6-dashboard-html.d.ts +1 -1
- package/dist/dashboard/v6-dashboard-html.d.ts.map +1 -1
- package/dist/dashboard/v6-dashboard-html.js +5 -27
- package/dist/dashboard/v6-dashboard-html.js.map +1 -1
- package/dist/dashboard/workspace-api.d.ts +10 -0
- package/dist/dashboard/workspace-api.d.ts.map +1 -0
- package/dist/dashboard/workspace-api.js +193 -0
- package/dist/dashboard/workspace-api.js.map +1 -0
- package/dist/dashboard/workspace-html.d.ts +2 -0
- package/dist/dashboard/workspace-html.d.ts.map +1 -0
- package/dist/dashboard/workspace-html.js +1555 -0
- package/dist/dashboard/workspace-html.js.map +1 -0
- package/dist/index.d.ts +4 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -0
- package/dist/index.js.map +1 -1
- package/dist/types.d.ts +4 -2
- package/dist/types.d.ts.map +1 -1
- package/docs/WORKSPACE.md +70 -0
- package/docs/assets/context-flow-v7.2.png +0 -0
- package/docs/assets/workspace-graph-v7.2.png +0 -0
- package/docs/assets/workspace-overview-v7.2.png +0 -0
- package/docs/launch/RELEASE_NOTES_v7.2.0.md +24 -0
- 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
|
-
|
|
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
|
-
|
|
5
|
+

|
|
6
6
|
|
|
7
|
+
*Concept illustration of the memory and context flow.*
|
|
7
8
|
|
|
8
|
-
|
|
9
|
+
## Get started
|
|
9
10
|
|
|
10
|
-
|
|
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
|
|
14
|
+
npm install -g @theihtisham/agent-shadow-brain@7.2.0
|
|
15
|
+
shadow-brain dash . --no-analysis
|
|
230
16
|
```
|
|
231
17
|
|
|
232
|
-
|
|
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
|
-
|
|
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
|
-
|
|
22
|
+
Version 7.2 opens a five-view workspace that runs locally and works offline.
|
|
299
23
|
|
|
300
|
-
|
|
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
|
-
|
|
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
|
+

|
|
306
31
|
|
|
307
|
-
|
|
32
|
+

|
|
308
33
|
|
|
309
|
-
|
|
34
|
+
*Screenshots from a running workspace populated with synthetic memories.*
|
|
310
35
|
|
|
311
|
-
|
|
36
|
+
Open **Advanced tools** or visit `/advanced` for the previous dashboard. [Workspace guide](docs/WORKSPACE.md)
|
|
312
37
|
|
|
313
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
50
|
+
## Add skills to a project
|
|
359
51
|
|
|
360
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
62
|
+
## Upgrade and reference
|
|
447
63
|
|
|
448
|
-
|
|
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
|
-
|
|
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.
|
|
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.
|
|
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"}
|