@theihtisham/agent-shadow-brain 7.2.0 → 7.22.0

package/docs/STATS.md

@@ -0,0 +1,21 @@
+# Package and repository statistics
+
+Last successful refresh: **2026-11-14T11:49:13.195Z**. Counts are snapshots from public npm and GitHub APIs.
+
+| Metric | Count | Coverage |
+| --- | ---: | --- |
+| npm total downloads | **6,229** | 2026-04-10 through 2026-11-13, inclusive |
+| npm latest day | 199 | 2026-11-13 through 2026-11-13 |
+| npm last 7 days | 923 | 2026-11-07 through 2026-11-13 |
+| npm last 30 days | 1,018 | 2026-10-15 through 2026-11-13 |
+| GitHub stars | 0 | At refresh |
+| GitHub forks | 0 | At refresh |
+| GitHub watchers | 0 | At refresh |
+
+The package was created on 2026-04-10. The total sums non-overlapping ranges of at most 365 days from creation through the latest complete day returned by npm. This handles the API's 18-month request limit without silently truncating lifetime counts. npm counts downloads, including automated installs; these are not unique people or active users.
+
+The dedicated **README metrics** workflow refreshes this page and the plain-text README total every two days. The npm README is a snapshot from the published release. A failed request preserves the last successful snapshot.
+
+[Raw snapshot and coverage](npm-metrics.json) · [npm download API documentation](https://github.com/npm/registry/blob/main/docs/download-counts.md) · [Package](https://www.npmjs.com/package/@theihtisham/agent-shadow-brain) · [Repository](https://github.com/theihtishaam/agents-brain)
+
+Historical snapshots in [stats-history.json](stats-history.json) come from the previous monitoring implementation and are not used to calculate this total.

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,42 @@
+# Troubleshooting
+
+## The Hub says Workspace unavailable
+
+Keep the launcher running and open the current URL. If an older tab points to a stopped server, start the same project on the same port and refresh. A port of `0` can change each time.
+
+```bash
+cd your-project
+shadow-brain project workspace . --port 62595
+```
+
+Open `http://127.0.0.1:62595/hub`. The status endpoint at `/api/workspace/status` reports the process instance, workspace mode, project scope, and storage health. A reachable server can report a storage error separately. Resolve the storage error before making changes and retain the existing project files. If the port is already in use, check the existing launcher or start on a free port and use the new address.
+
+## The installed version differs from this guide
+
+This guide describes the 7.1.4 build. It requires Node.js 22.13+ in the 22.x line, 24.x, or 26+.
+
+```bash
+node --version
+npm install -g @theihtisham/agent-shadow-brain@latest
+shadow-brain --version
+```
+
+If the command still reports the previous version, locate it with `Get-Command shadow-brain -All` in PowerShell or `command -v shadow-brain` in your shell. Restart the launcher after changing versions. A browser refresh alone continues using the old process.
+
+## The graph or journal is empty
+
+Check the selected project. Save a knowledge record or approve a PDF page to create a graph record. Connect a host using the recipe generated from the same project directory. In **Setup**, enable **Live dashboard activity** and **Record agent activity**. Ask the host to call `project_inspect` or `context_pack`, then look for the event. A reachable workspace and installed skill files are independent of host tool activity.
+
+## A feature setting or claim changed elsewhere
+
+Refresh to read the current revision before retrying. For a task claim, check its owner and lease. After a network failure, retry the same input to reuse the operation key. The work room and journal use different stores and can be inspected independently.
+
+## A PDF page has no text
+
+Image-only pages require OCR. The current Hub extracts a text layer and labels missing text. Upload a text-searchable PDF or save a verified excerpt as explicit project knowledge with its reference.
+
+## A context pack is empty or shorter than expected
+
+Check that the selected project contains relevant active memories, the context feature is enabled, and the token budget allows an excerpt. Try specific project terms. Context estimates describe the rendered pack. Model usage stays unavailable when the host supplies no usage receipts.
+
+[Quickstart](QUICKSTART.md) · [Workspace guide](WORKSPACE.md) · [Integrations](INTEGRATIONS.md)

package/docs/UPGRADE_PLAN_v7.0.0.md

@@ -0,0 +1,203 @@
+# Agent Shadow Brain upgrade plan
+
+Prepared: 2026-11-11. Baseline inspected: published `@theihtisham/agent-shadow-brain@6.3.0`. Target release: 7.0.0. This is an implementation and release plan, not a completion claim.
+
+## Objective and roles
+
+Make the existing shared memory layer dependable when multiple agents write, and make recalled memory scores reflect the evidence actually available. Preserve local-first operation, existing CLI/API/MCP entry points, and existing JSON memories.
+
+Astra serves as architecture and review lead: choose scope, establish invariants, inspect failure cases, and review the release evidence. GPT 6.1 SoL serves as implementation lead: recover or locate the authoritative checkout, implement the approved scope, run verification, and publish the exact reviewed artifact. These are execution roles for this work; they do not imply adding model-provider integrations to the product.
+
+Release theme: **Reliable shared memory and explainable recall**. Initial planning targeted 6.4.0; implementation discovery justifies **7.0.0** instead. Patched dependency majors require a higher Node baseline, installation no longer runs automatic setup, and unreadable/corrupt stores now fail visibly instead of silently resetting. These compatibility changes deserve a major version. Confirm 7.0.0 remains unpublished immediately before release.
+
+## Evidence from the published package
+
+The package advertises a shared source of truth across projects and agents. Its `GlobalBrain` currently loads a JSON snapshot once and writes the whole snapshot back on every dirty sync. The publication includes compiled JavaScript and declarations; inspected source maps refer to TypeScript paths but do not embed source contents. The repository URL in package metadata was not accessible during the initial source search.
+
+Source recovery update: the parent agent recovered the exact published npm `gitHead`, `bec756e19647a11cad570f8ae3c363792de84856`, from public fork `shadrackohemeng/agent-shadow-brain`. Full source is checked out under `work/agent-shadow-brain` (initial working branch `upgrade/6.4.0`, release target subsequently revised to 7.0.0). This preserves actual source/history and removes the need to reconstruct TypeScript from the distribution. Initial publication checks found the recorded GitHub upstream inaccessible and npm reporting `ENEEDAUTH`. The coordinating agent subsequently reported successful npm authentication after the user logged in manually; no credentials were requested in chat or inspected by this reviewer. The coordinating agent verified the current GitHub account as `ihtishaam-dev` through `gh api user` and announced `ihtishaam-dev/agent-shadow-brain` as the destination for the user-authorized GitHub upload because the original owner/repository was unavailable. Repository creation and remote publication remain pending until verified; this is the intended current-account destination, not a claim that the original remote was recovered.
+
+Baseline verification update from the coordinating agent: TypeScript build passed; 171 of 172 baseline tests passed, with the remaining test tied to a fixed June date and failing against the current November date. Make its clock deterministic. Dependency audit reported 14 advisories (4 critical, 7 high, 3 moderate). The coordinating agent is upgrading the affected direct/development dependencies and will record the final audit after verification. Planned Node support is `^22.12.0 || ^24.0.0 || >=26.0.0`; the final manifest and CI must agree, and only actually tested versions may be claimed as verified.
+
+Implementation review update: the coordinating agent reported the migrated dependency audit at zero advisories and the corrected baseline at 172 passing tests. Astra reviewed the rewritten GlobalBrain lock, merge, acknowledgement, read-refresh, and scoring paths and found no blocker in the initial static pass. The independent built-output probe `work/audit/v7-independent-review.mjs` passed: simultaneous instance additions; external-read refresh; summed access deltas; queued writes arriving during a held-lock wait; preserved malformed-store bytes; false acknowledgement on failure; exactly-once retry; and unchanged bytes/modification time after a read-only lifecycle. All review fixtures were synthetic and explicitly located beneath `work/audit/fixtures`. Actual multiprocess contention tests, full final suite, exact tarball checks, and publication verification remain separate release gates.
+
+Core review gate update: SoL reported all 22 focused storage/scoring tests passing. Astra inspected the test implementation, including four actual Node processes synchronized after initialization, 40 exact unique acknowledged IDs, and restart verification. The failure tests cover EPERM with preserved previous bytes, retry, old live locks, late queued operations, corrupt/future/unreadable stores, and read-only refresh. Astra accepted the core implementation with no blocking finding. Full final suite, exact release tarball, remote CI, and publication are still independently verified by the coordinating agent. These results do not claim crash-recovery automation, coordination with old v6 writers, power-loss guarantees, network-filesystem safety, or a full codebase security audit.
+
+Final local release-gate evidence, reported by the coordinating agent: all **192 tests across 19 files passed**; build and lint passed; `npm audit` reported **zero vulnerabilities**; and a packed-artifact fresh-consumer installation passed library import, CLI version/help, durable write, storage-health, explained recall, corrupt-store preservation, package-content, and configuration-isolation checks. The dashboard tooltip now states that the score is heuristic rather than a probability of truth, and identifies creation-age recency and matching-content agent reports. No additional test rerun was needed for this documentation-only update. Local engineering/review gates are complete. Remote GitHub creation/push/tag, registry publication/integrity, dist-tag verification, and remote CI remain pending verification by the coordinating agent.
+
+Three deterministic probes were executed against the published `global-brain.js`, using newly created stores only under `work/audit/fixtures`. They imported only the inspected global-brain module and its in-process bus dependency. They did not run package setup, attach hooks, read the user's memory store, or inspect private credentials.
+
+| Priority | Finding | Evidence | User impact |
+| --- | --- | --- | --- |
+| P0 | A writer replaces other agents' memories | Two independent instances initialized before either write each added a different entry. After both synced, disk contained one entry, not two. | The core cross-agent promise can silently lose memory. |
+| P0 | A queued write reports success before disk commit | Making the fixture destination temporarily unwritable caused `sync()` to throw `EPERM`, while `write()` still resolved `true`. | Agents can report durable learning that was never saved. |
+| P1 | Unrelated agents inflate apparent corroboration | A target memory scored 0.595/medium. Two unrelated entries in other projects but the same category raised it to 0.695/high. | The dashboard and agents may overtrust uncorroborated facts. |
+| P1 | Relevance is constant for every query match | `computeConfidence()` assigns 0.9 whenever meaningful keywords were supplied, independent of how many matched or where. | Weak matches can outrank relevant memories through unrelated popularity signals. |
+| P1 | Persistence uses one shared temporary filename | `persist()` writes `dbPath + '.tmp'` without an interprocess lock. | Concurrent processes can race on both the database and temporary file. |
+| P1 | Store read failures are treated as corruption | Broad initialization catch attempts to rename the store and continue with an empty brain. | Permission or transient read failures can become silent resets. |
+| P2 | Numeric and date inputs lack defensive normalization | Non-finite importance, negative counts, and invalid dates can propagate to scoring; raw limits are sliced directly. | Scored results can disappear or serialize invalid values unexpectedly. |
+| P2 | Package/runtime claims need reconciliation | Node engine declares >=18 while dependencies may require newer Node; auto-setup prints v5.2.0 and the README includes stale/broken image references and an unrelated Trendshift badge. | Installation and release identity may differ from documentation. |
+
+Reproduction: `node work/audit/published-global-brain-probe.mjs`. Its fixture data is synthetic. Keep this baseline evidence separate from the final implementation tests.
+
+## Scope for the release
+
+Ship these together because they establish one contract: a memory accepted as saved survives cooperating writers, and its ranking is explained honestly.
+
+1. Preserve concurrent writes, registrations, and access updates through a bounded, explicit interprocess commit protocol.
+2. Acknowledge queued writes only after successful persistence; preserve failed pending operations for an explicit retry contract.
+3. Distinguish unreadable, malformed, and unsupported stores. Never silently replace an unreadable or newer-schema store with an empty one.
+4. Compute relevance from normalized query matches; remove category-wide diversity as a claim of factual agreement.
+5. Normalize malformed legacy ranking fields without modifying the source file merely because it was read.
+6. Expose accurate scoring language and additive explanations through existing consumers; keep old response fields available.
+7. Add meaningful failure and concurrent-process tests, package verification, release notes, and a reproducible release manifest.
+
+Defer feature breadth: autonomous publishing, new remote providers, cloud sync, vector database migration, model training, new agent swarms, and a dashboard redesign. None solves the reproduced failures. Do not claim a full security audit of the entire large existing feature surface from this bounded review.
+
+## Phase 0 — Establish source provenance and a safe baseline
+
+- Locate the authoritative working tree and inspect its local instructions and git state. Preserve all unrelated user work.
+- Verify the intended upstream and package identity with public metadata or the connected GitHub capability. A 404 does not establish whether the repository is deleted, renamed, private, or simply inaccessible.
+- Do not read `.npmrc`, credential files, browser stores, authentication secrets, or unrelated home-directory files to solve access issues.
+- If original source cannot be found, clearly label a reconstruction from the public npm artifact and document its limitations. Do not fabricate commit history, tests, or absent source contents. A source reconstruction requires sufficient buildable coverage and provenance before release; an unpacked `dist` directory alone is not equivalent to a maintainable source checkout.
+- Record the npm tarball integrity, installed version, source commit when available, and initial dirty state. Install dependencies with lifecycle scripts disabled in the isolated checkout. Run no global installation, hook attachment, setup, auto-update, or user's default brain initialization.
+- Run an isolated baseline build/test where the source permits it. Record existing failures independently of new regressions.
+
+Gate A: buildable source is identified; the three published failures are captured; the intended publication destination is verified or explicitly recorded as an external blocker. Engineering work can continue while publication access is unresolved.
+
+### Implementation ownership and shared contracts
+
+SoL owns `src/brain/global-brain.ts`, relevant `src/types.ts` additions, and focused storage/scoring tests. The coordinating agent owns test isolation, package/release configuration, CLI/MCP integration, documentation, and publication. Astra reviews both the storage invariants and final evidence.
+
+Expose `GlobalBrain.getStorageHealth()` with this additive shape so integrations can proceed independently:
+
+```ts
+interface GlobalBrainStorageHealth {
+  status: 'healthy' | 'pending' | 'error';
+  dbPath: string;
+  initialized: boolean;
+  pendingOperations: number;
+  lastSuccessfulSync: string | null;
+  lastError: { code: string; message: string; at: string } | null;
+}
+```
+
+Use ISO timestamps; return a copy, never mutable internal state. `status: 'error'` takes precedence when the last attempted commit failed and has not subsequently succeeded; an uninitialized store is distinguishable through `initialized`. Keep diagnostic messages free of memory contents. A configurable optional `lockTimeoutMs` may default to 5000 ms. The health command must not inspect credentials, attach integrations, or initialize unrelated services. Reads may inspect only the explicitly selected brain store; tests always select synthetic fixture paths.
+
+## Phase 1 — Define and implement memory commit invariants
+
+### Required invariants
+
+- An acknowledged asynchronous write exists in the committed store after restart.
+- Every distinct acknowledged write from cooperating processes survives subsequent commits.
+- The database is always either the previous valid JSON or the next valid JSON; readers never observe a partially written payload.
+- Read/parse/permission failure cannot cause a commit based on an assumed empty store.
+- The process never removes another live writer's lock or temporary file.
+- Shutdown clears its timer even when flush fails, and reports flush failure to callers.
+- A long-lived reader refreshes external committed changes on an explicit/periodic sync, even when it has nothing to write. This refresh is read-only; cross-process visibility is bounded by the configured refresh interval, not claimed to be instantaneous.
+- `writeSync()` retains its existing immediate ID-return behavior; documentation explicitly says it stages an in-memory change until `sync()`/shutdown commits. Do not falsely relabel it as durable synchronous I/O.
+
+### Recommended architecture
+
+Keep the existing JSON format for compatibility, but replace full-snapshot overwrite with a pending-operation commit path. Track additions, project/agent registrations, access-count increments, and explicit deletions separately from the loaded snapshot. The operation queue should preserve the IDs generated when callers originally wrote, so retries are idempotent.
+
+Acquire an exclusive filesystem lock adjacent to the configured database using an atomic filesystem operation. Use bounded asynchronous retry and a clear timeout error, not indefinite busy-waiting. Release only a lock whose ownership token matches the current writer. Do not infer that an old timestamp alone proves the owner is dead: if recovery is implemented, test liveness and race conditions conservatively; a bounded error is safer than stealing a live lock.
+
+While holding the lock, read and validate the latest disk snapshot. Apply this writer's pending operations to that snapshot and preserve unfamiliar fields wherever compatible. Add new entry IDs once; apply access increments as deltas; merge registration timestamps monotonically. A stale writer must not reintroduce an entry explicitly deleted by another writer. If prune semantics cannot be made correct within this release, narrowly defer automatic pruning during concurrent commit and document that choice rather than merge whole stale maps.
+
+Write a unique sibling temporary file opened exclusively, flush the file where supported, and atomically replace the database. Use `try/finally` to close handles and clean up only this writer's files. Account for Windows rename errors without deleting the last valid destination first. Avoid promising full power-loss durability unless filesystem/directory flush behavior is tested on the supported platforms.
+
+Only after successful replacement: resolve accepted queued writes `true`, update in-memory state from the committed merged snapshot, clear committed operations, set last-sync status, and publish durable-commit events if introduced. On failure: report the error, keep operations retryable, and never claim successful persistence. Choose and document whether the original `write()` promise resolves `false` immediately while operations remain queued, or stays pending until a later successful retry; tests and callers must agree.
+
+Treat a missing file as a new store only on the specific missing-file error. Validate top-level shape and schema before merging. A corrupt-store backup/recovery workflow must preserve the original bytes and be explicit. Unsupported future schemas fail closed. Avoid introducing automatic destructive migration.
+
+### Tests that matter
+
+- Two stale instances, both flush orders, then reopen: both entries survive.
+- A read-only instance syncs after another writer commits: recall sees the externally committed entry without rewriting the store.
+- Multiple actual Node processes synchronize on a barrier and write many distinct entries: exact expected ID set survives, JSON parses, no duplicate IDs.
+- A writer registers a project while another adds a memory: both survive.
+- Two writers touch the same entry: access increments are merged correctly and timestamps do not move backward.
+- A stale writer commits after a prune/delete: deleted entries are not resurrected.
+- Forced write/rename failure: no true acknowledgement, prior valid DB remains intact, retry commits exactly once.
+- Held lock: bounded timeout, no stolen lock, no deletion of another writer's temp file.
+- Malformed JSON, permission failure, unsupported schema: error is visible, original bytes are preserved.
+- Shutdown with pending writes and shutdown under error: promise/timer behavior is deterministic.
+
+Gate B: these tests pass against temporary databases; the published loss and false-acknowledgement probes are corrected; reviewer inspects lock ownership and failure cleanup.
+
+## Phase 2 — Make recall relevance and trust signals honest
+
+Create one shared keyword normalization path for matching and scoring. Normalize case and whitespace, remove duplicates and documented stop words, and distinguish an empty meaningful query from a real query. Do not use one normalization rule in `recall()` and another in `recallScored()`.
+
+Compute relevance from actual matched query terms and field contributions. Content/category evidence should dominate a match on project name alone. Keep scores finite and within [0,1], and retain stable deterministic ties. Apply metadata/project/agent filters before computing the candidate universe. Evaluate the complete bounded filtered candidate set rather than allowing an arbitrary pre-score top-60 cutoff to exclude the best scored result; document any explicit safety cap.
+
+Remove the current claim that different agents writing anything in a category constitute corroboration. A conservative compatible repair is to keep the `signals.corroboration` field at zero unless explicit corroboration evidence is defined and validated. If implementing a duplicate-fact heuristic, restrict it to the same project and normalized factual content, count distinct agent identities, and label it independent reports rather than proof of truth. Copied text and fabricated agent labels are not verified independent evidence.
+
+Do not equate last access with source freshness. Preserve the existing recency field for compatibility but clarify its meaning, or use creation/explicit verification time with a documented change. Access popularity is a ranking aid, not factual validation. Unknown or invalid timestamps must have conservative finite handling; negative/non-finite importance and access counts must not create NaN or inflate trust.
+
+Retain the `confidence.score`, `level`, and `signals` shape. Add optional explanation/matched-term fields only if consumers need them. Describe the value as a heuristic recall score, not a calibrated probability that a statement is true. High scores never supersede source verification or project instructions.
+
+Tests: one of several query terms versus all terms; category-only versus content matches; unrelated same-category entries in other projects; duplicate keywords; stop-word-only query; mixed casing; malformed legacy dates/counts; fractional/negative/non-finite limits and thresholds; deterministic tie ordering; score filtering; project isolation; queries large enough to expose the old candidate cutoff.
+
+Gate C: unrelated memories no longer change a target's corroboration score; stronger query matches rank appropriately; every emitted score/signal is finite; response compatibility is preserved.
+
+## Phase 3 — Integrate existing surfaces and document behavior
+
+- Route MCP and dashboard recall through the same options validation and scoring behavior. The current `global_recall_scored` MCP tool already exists; extend it instead of creating duplicate tools.
+- Preserve existing endpoint names and flags even where names are project-specific. A generic alias is additive if worthwhile, not a reason to break clients.
+- Make any cross-project fallback explicit in the response and visible in the interface. Existing dashboard code already shows a fallback warning; preserve this behavior.
+- Update dashboard score labels/tooltips and type comments to avoid implying factual corroboration or calibrated truth confidence.
+- If exposing storage health, report last successful commit, pending count, and last failure without dumping memory content or filesystem secrets.
+- Audit changed UI interpolation for escaping. A static audit already found activity-log `innerHTML` interpolation of event details; either fix this small directly related unsafe rendering path with a malicious-text regression fixture, or disclose it as a separately tracked pre-existing issue. Do not execute untrusted markup in a real user browser.
+- Resolve version strings in changed release surfaces and include valid npm-facing images or remove broken references. Remove the unrelated Trendshift badge rather than implying unrelated popularity.
+- Reconcile the declared Node minimum with dependency engines and test matrix. Raising it is a compatibility decision that must be explicit, not a silent metadata edit.
+
+Gate D: API/MCP fixture tests exercise real changed handlers where practical; package CLI/API smoke tests use isolated temporary homes/stores after inspecting startup paths; docs accurately describe persistence, ranking, limitations, and install behavior. Browser UI is not used without the user's request under the user's privacy instructions; static rendering tests are not reported as visual browser acceptance.
+
+## Phase 4 — Verify the exact distributable
+
+Run TypeScript checking/build, focused regression tests, then the available full suite. Record commands, runtime versions, counts, failures, and exit codes. Investigate new failures; preserve a clear separation between pre-existing failures and this change. Do not describe a partial or skipped suite as a full pass.
+
+Create the actual npm tarball with lifecycle scripts disabled where required. Inspect its file manifest: source maps/declarations align, entry points and CLI shebangs exist, no fixture stores, logs, private state, test artifacts, or credentials are included. Test installation and imports from this exact tarball in a fresh sandbox. Inspect postinstall behavior before executing it; it must not mutate the user's environment during verification.
+
+Run the concurrent-writer and restart probe against the installed packed output, not only TypeScript test imports. Confirm package version, runtime-visible version, and release documentation agree. Validate the minimum supported Node version or clearly state which versions were actually exercised.
+
+Produce a release manifest containing source commit, version, artifact filename, SHA-256/SHA-512 or npm integrity, test summary, and known limitations. Retain the previously published tarball and git checkpoint for rollback reference; do not touch the user's live memory store.
+
+Gate E: the exact artifact intended for publication passes isolated verification and the review lead approves the concrete diff and evidence.
+
+## Phase 5 — GitHub and npm release
+
+The user has requested upload to GitHub and npm; no extra generic confirmation is needed for that authorized destination. Publishing still requires a verified repository and usable authenticated capability. Use connected tools or an already configured publishing command without opening or printing credential stores. Never request a token, password, recovery code, or OTP to be pasted into chat. If authentication is unavailable or interactive approval is required, identify that precise external blocker after completing the reviewable local work.
+
+1. Confirm version availability and verified upstream target; avoid overwriting existing immutable npm versions or unrelated repository history.
+2. Commit the reviewed source and documentation; push the intended branch/tag through the authorized capability. Confirm the remote commit matches the reviewed local commit.
+3. Publish the exact tested tarball at the chosen version/tag. Do not rebuild different bytes after verification without repeating package checks.
+4. Read public registry metadata and fetch the published tarball to verify version and integrity. Smoke-test the public artifact in a new isolated directory.
+5. Verify GitHub visibility, release/tag identity, npm version/dist-tag, and installation separately. A successful local build is not proof of a GitHub push or npm publication.
+6. Report actual outcomes with links and any external blockers. If one destination succeeds and the other fails, say so explicitly and retain the artifact for a controlled retry.
+
+Rollback: restore a prior known-good version through the appropriate distribution tag or publish a corrective version; do not assume deleting a public version is safe or allowed. Keep old-schema reading compatible so rollback does not require destructive memory conversion. Document that downgrade to older writers reintroduces their lack of locking; do not promise concurrent safety with old and new writer versions mixed.
+
+## Follow-on roadmap after this release
+
+1. Evidence lifecycle: explicit source references, verification timestamps, superseded/conflicting memories, source-change detection, and transparent review queues.
+2. Storage evolution: benchmark real memory sizes and contention, then consider a transactional store behind an adapter with tested export/rollback. Do not rewrite storage solely for fashion.
+3. Retrieval evaluation: held-out realistic queries with relevance judgments and ablation comparisons. Measure retrieval utility separately from factual correctness; report results instead of claiming intelligence gains without evidence.
+4. Safer integration management: idempotent attach/detach, config backups, previewable mutations, and platform-specific compatibility checks.
+5. Dashboard and network boundary audit: escaping, request methods, origin checks, loopback defaults, and optional offline asset bundling. This requires a separate defined audit scope.
+6. Operational clarity: health reports, explicit persistence errors, schema compatibility reports, and measured recall/commit latency under load.
+
+## Release completion checklist
+
+- [x] Authoritative source/provenance and intended current-account repository destination established; remote creation/push is a separate gate.
+- [x] Memory-loss and false-success regressions repaired and tested with real processes.
+- [x] Lock, corruption, schema, and retry failure paths reviewed.
+- [x] Recall scores use actual relevance and conservative corroboration.
+- [x] Existing clients and existing JSON stores remain supported as documented.
+- [x] Changed dashboard output is escaped and labels are accurate.
+- [x] Build, relevant tests, and packed-artifact checks recorded.
+- [ ] Release artifact, source commit, and integrity recorded.
+- [ ] GitHub remote commit/tag verified, or precise external blocker reported.
+- [ ] npm public version/integrity verified, or precise external blocker reported.
+- [ ] Final response distinguishes implemented, tested, uploaded, and externally verified outcomes.

package/docs/VIRAL-PLAYBOOK.md

@@ -0,0 +1,259 @@
+# Shadow Brain — Viral Launch Playbook
+
+> **For:** @theihtisham — execute personally; do NOT delegate
+> **Goal:** v6.0.2 "Singularity" reaches **HN front page**, **#1 trending on GitHub**, **10k stars in 30 days**
+> **Honest disclaimer:** Virality is not engineered, only set up. This playbook maximizes the chance, but timing + luck + thumbnail matter.
+
+---
+
+## The Thesis
+
+Hermes Agent, Devin, Cursor, Cline didn't go viral because they were *more featured*. They went viral because they showed **one undeniable thing the world hadn't seen**. For Shadow Brain v6.0.2, that thing is:
+
+> **"Your codebase becomes its own model. Watch your AI agents share a single brain — and produce shareable proof."**
+
+The 5 viral features (Replay, DNA, Hive Voice, Time Capsule, Diff) are designed to **produce screenshots that people retweet**. The product is the marketing. Every artifact is a thumbnail.
+
+---
+
+## The 4-Phase Launch
+
+### Phase 0 — T-7 days: Build the seed (in private)
+
+- [ ] **Record the hero demo** — 90 seconds, no narration, just the dashboard + 3 viral features in action. Upload as MP4 to repo and to a Twitter-friendly host.
+- [ ] **Generate 5 Brain DNA cards** — for 5 different real public repos (React, Django, your own repo, an Anthropic SDK, a Hacker News favorite). Save as PNG.
+- [ ] **Generate Brain Replay SVG** for at least 1 mid-sized real project. Polish the gradient/colors so it looks like a poster.
+- [ ] **Generate a Hive Voice SVG** answering a hot question ("Should you use Server Components by default in 2026?"). Make it look like an FOMC bar chart.
+- [ ] **Run SWE-Bench-Lite once** locally if compute allows — get *real numbers*. "+33% resolution rate" beats "potentially huge."
+- [ ] **Pre-seed 5 GitHub issues** with discussions / FAQs / known limitations — looks alive on day 1.
+- [ ] **Update the README banner** with a still from the hero demo.
+- [ ] **Buy the domain** `shadow-brain.dev` and `brain.dev` if available; just park them.
+
+### Phase 1 — Launch day (Tuesday, 09:00 PT)
+
+The launch tweet **leads with the SVG**, not the link.
+
+#### Tweet 1 (with Brain DNA card image):
+```
+your codebase has a personality.
+
+mine is "The Architect."
+
+i built shadow brain — every AI coding agent on your machine shares one local brain.
+v6.0.2 ships 5 things nobody else has.
+
+🧵
+```
+
+#### Tweet 2 (with Brain Replay timeline SVG):
+```
+1/ Brain Replay
+
+scrubbable timeline of every decision, memory, and insight your hive has made — since day zero.
+
+drag the cursor. watch your project learn.
+
+[gif of scrubbing the timeline]
+```
+
+#### Tweet 3 (with Hive Voice bar chart):
+```
+2/ Hive Voice
+
+3 local models vote on every architecture decision.
+you see consensus, dissent, and confidence distribution. live.
+
+no more "the AI said so." now you see the AIs argue.
+```
+
+#### Tweet 4 (with Time Capsule screenshot):
+```
+3/ Brain Time Capsule
+
+freeze your brain. label it. resurrect it in 6 months.
+
+"here's what we knew about React in January."
+"here's what we thought about Supabase before the migration."
+
+git, but for intelligence.
+```
+
+#### Tweet 5 (with Brain Diff Venn):
+```
+4/ Brain Diff
+
+diff two brains semantically.
+
+"what did Team A learn that Team B didn't?"
+
+[Venn diagram SVG]
+
+now you know what to teach.
+```
+
+#### Tweet 6 (with sample LoRA conversation):
+```
+5/ Project-LoRA
+
+every week, distill your brain into a LoRA adapter on Qwen2.5-Coder-1.5B.
+
+your codebase becomes a model.
+
+runs locally via Ollama. zero cloud. zero per-token cost.
+```
+
+#### Tweet 7 (the close):
+```
+shadow brain v6.0.2 — "Singularity"
+
+local-first
+free forever
+MIT license
+zero telemetry
+
+$ npm i -g @theihtisham/agent-shadow-brain
+$ shadow-brain demo
+
+→ github.com/theihtisham/agent-shadow-brain
+```
+
+### Phase 1 — Launch day, simultaneous posts
+
+#### Hacker News (Show HN, ~09:30 PT same morning):
+```
+Show HN: Shadow Brain — 5 features no other AI coding agent has
+
+Title is honest, not clickbait. Body:
+
+I got tired of explaining the same context to Claude Code, then Cursor, then Cline. Every session, every agent, from zero.
+
+So I built Shadow Brain. One local brain. Every agent — Claude Code, Cursor, Cline, Aider, Copilot, Codex, Windsurf, OpenCode — shares it. What one agent learns, every agent inherits. 100% local. MIT.
+
+v6.0.2 ships 5 things I haven't seen anywhere else:
+
+1. Brain Replay — scrubbable timeline of every brain event since day zero. SVG exports.
+2. Brain DNA — Spotify-Wrapped-style fingerprint card per codebase. Shareable PNG.
+3. Hive Voice — multiple local models vote on every question. See dissent + confidence live.
+4. Brain Time Capsule — freeze + resurrect brain states. "Here's what we knew in January."
+5. Brain Diff — semantic diff between two brains. Venn diagram output.
+
+Plus: real ANN vector index, Constitution layer, Confidence Gate, multimodal vision, LoRA distillation pipeline, SWE-Bench-Lite eval harness.
+
+GitHub: github.com/theihtisham/agent-shadow-brain
+npm: @theihtisham/agent-shadow-brain
+30-second demo: $ npm i -g @theihtisham/agent-shadow-brain && shadow-brain demo
+
+Honest about the limits in the README. Honest about the v7 roadmap. Honest that I'd love your feedback.
+
+— theihtisham
+```
+
+#### Reddit /r/LocalLLaMA + /r/MachineLearning + /r/programming
+Drop the same thread, customized last paragraph per sub.
+
+#### LinkedIn (longer-form post):
+- Lead with "Why I built this" (1 paragraph)
+- The 5 features
+- Link
+
+#### Bluesky + Mastodon (same as Twitter, formatted)
+
+### Phase 2 — Day 1-3 amplification
+
+- [ ] **Respond to every HN comment within 30 minutes** for the first 6 hours
+- [ ] **Live-tweet the metrics** ("Hour 4: 500 stars · 12 PRs · 3 issues fixed")
+- [ ] **DM the 50 most-relevant influencers personally** (no spam, only if their bio screams "AI coding tools" — and only AFTER they've posted publicly today)
+- [ ] **Reply to every Twitter mention** for 48 hours
+- [ ] **Open 5 RFC issues** for community design input — makes it look like a project, not a launch
+- [ ] **Submit to Product Hunt** on day 2 (separate hit, different audience)
+- [ ] **Submit to Indie Hackers** end of day 2
+
+### Phase 3 — Week 1-2 follow-through
+
+- [ ] **Blog post** on Substack/dev.to: "How I built Shadow Brain" — technical deep-dive
+- [ ] **Podcast outreach** — DM 5 podcasts (Latent Space, ThePrimeagen, Lex if you're bold, etc.)
+- [ ] **YouTube long-form** — 20-minute "build a brain pack for X" walkthrough
+- [ ] **Twitter Spaces / X Space** — host a "build your brain" hour
+- [ ] **GitHub Discussions** — pin 3 community challenges
+- [ ] **Brain Exchange seed launch** — week 2: 5 starter packs go live
+
+---
+
+## What to NOT do
+
+These are the most common launch mistakes. Don't.
+
+- ❌ **Don't lead with a wall of text.** Lead with the SVG/PNG. Image-first, always.
+- ❌ **Don't oversell.** "Disrupts AI coding forever" reads as cringe. "5 things no one else has" reads as confident.
+- ❌ **Don't @ random influencers in your launch tweet.** Looks needy. They'll find it if it's good.
+- ❌ **Don't argue with cynics in the replies.** Pin the demo GIF instead. Let the artifact do the talking.
+- ❌ **Don't gate features behind sign-up.** Anything that asks for an email before showing value gets memed.
+- ❌ **Don't claim numbers you didn't measure.** "+33% resolution on 10 SWE-Bench-Lite problems" is fine. "5× faster than Cursor" without a benchmark is not.
+- ❌ **Don't ship the launch tweet during US lunch / European evening / Asian sleep.** 09:00 PT Tuesday. Otherwise wait.
+
+---
+
+## The Metrics That Matter
+
+Track these. Post them publicly when they hit milestones.
+
+| Metric | Day 1 target | Week 1 target | Month 1 target |
+|---|---|---|---|
+| GitHub stars | 500 | 3,000 | 10,000 |
+| npm weekly downloads | 200 | 2,000 | 10,000 |
+| HN front page rank | top 30 | — | — |
+| Twitter impressions | 100k | 500k | 2M |
+| Reddit upvotes (combined) | 200 | 1,000 | 3,000 |
+| Brain Exchange packs (community) | 0 | 3 | 10 |
+| GitHub forks | 50 | 200 | 800 |
+| Public users (npm install) | 200 | 2,000 | 10,000 |
+
+If you don't hit Day 1 targets — don't panic, but **post a public retrospective**. Honesty about a flat launch wins later goodwill.
+
+---
+
+## The "Crazy" Quote-Tweets To Pre-Write
+
+People retweet *because of a quote*. Pre-write 10 of these so you can drop them when momentum picks up.
+
+1. *"AI coding tools today: every session, every agent, from zero. Shadow Brain: one brain, every agent, infinite memory. Local. Free. MIT."*
+2. *"I think Cursor / Cline / Aider are great. None of them remember anything across sessions. Shadow Brain fixes that — for all of them simultaneously."*
+3. *"The hot take: AI coding 'memory' is a solved problem. We just hadn't built it open-source yet."*
+4. *"Your codebase has a personality. Mine is 'The Architect.' Generate yours."*
+5. *"Hive Voice is what the AI safety community has been asking for, packaged in a way devs will actually use."*
+6. *"Brain Time Capsule is git for intelligence. We git'd code in 2005. We're git'ing intelligence in 2026."*
+7. *"Project-LoRA: every week, your codebase becomes a model. Try doing that with a SaaS coding tool. (You can't.)"*
+8. *"The honest pitch: this is the AI memory infrastructure I wish existed when I started. So I built it. MIT."*
+9. *"No telemetry. No cloud. No surveillance. Just one local brain your agents share."*
+10. *"Devin proved the agent. Cursor proved the editor. Shadow Brain proves the memory."*
+
+---
+
+## After Launch — The Compounding Plays
+
+Once the initial surge is over, what makes the project keep growing?
+
+1. **Brain Exchange marketplace** — UGC content compounds organically
+2. **VS Code extension** — discoverability bump from Marketplace
+3. **GitHub Action** — every PR that merges advertises the brain
+4. **Public leaderboard** — SWE-Bench numbers updated monthly
+5. **Conference talks** — submit to ML conferences with the LoRA distillation paper
+6. **Academic paper** — publish "Local-First Shared Memory for AI Coding Agents" on arXiv
+
+---
+
+## Final Honesty
+
+This playbook maximizes chance, not certainty. Most launches don't pop. The ones that do, do because:
+
+1. The *thing itself* is genuinely new (yes, here)
+2. The *artifacts* are inherently shareable (yes, the 5 SVGs)
+3. The *timing* lines up (Tuesday 09:00 PT, not during a major event)
+4. The *narrative* is clear in 1 sentence ("every AI agent shares one local brain")
+5. The *founder shows up* in the replies for 48 hours (this is on you)
+
+If 1-4 are in place and you do 5 — the upside is real. If you skip 5, the upside is 80% smaller.
+
+Go.
+
+— playbook generated by the brain for the brain

package/docs/VISUAL_GUIDE_v7.1.4.md

@@ -0,0 +1,70 @@
+# A visual guide to Agent Shadow Brain
+
+The control room captures use an isolated store containing 74 excerpts from 18 public Agent Brain documents, with 54 links backed by Markdown references in the excerpts. The journal records three measured calls from a scripted local MCP client. The workflow screenshots farther down use separate synthetic fixtures and carry an on-screen label. [Public documentation snapshot](https://github.com/theihtishaam/agents-brain/tree/2e26e7b349db4dd75bf0277b28caff8044190d16)
+
+## Open the control room
+
+![Animated Brain Hub with public documentation, focused memory, and measured MCP activity](assets/7.1.4-hub-public-docs.gif)
+
+Start `shadow-brain project workspace . --port 62595` and open `/hub`. The header confirms whether the local workspace responded. A reachable workspace can have no host activity. When the process stops, the page retains its loaded snapshot and retries. Restarting the same project on the same port restores the route.
+
+![The control room with actual documentation references and a measured context tool receipt](assets/7.1.4-hub-public-docs.png)
+
+| Visual | Evidence |
+| --- | --- |
+| Cyan graph links | A memory belongs to a project. |
+| Pink graph links | A memory was recorded by an agent or operator. |
+| Amber graph links | A persisted typed relationship. |
+| Moving highlight | A fresh journal record whose project and author are both present in the graph. Measured events use cyan and explicit reports use amber. The arc locates an event in the graph. |
+| Faint outer outline | A placement guide for the stored nodes. |
+| Inspector | Stored record, source references, links, or a selected journal event. |
+
+Choose a node with the pointer or open **Node list** and select it with the keyboard. **Clear focus** restores the surrounding relationships. **Trace** lists retained journal events. Seek with the slider or select a timeline row. **Latest** follows new events. **Pause motion** and the system reduced-motion preference stop animation.
+
+![Focused public documentation excerpt with its actual repository-relative source path](assets/7.1.4-hub-public-docs-source.png)
+
+![A reachable empty project with zero real graph records](assets/7.1.4-hub-empty.png)
+
+## Approve a cited page
+
+![Extracted PDF text and the approved source page in Knowledge](assets/7.1.4-hub-knowledge.png)
+
+Upload a project PDF and open a page. Review its extracted text and citation before approving it into the project’s memory. Uploading identical bytes returns the existing document. Image-only pages require OCR, which this build does not provide. **Add knowledge** accepts explicit text. The **Project skill** form previews a generated host skill and applies that exact plan after review.
+
+## Share a workstream
+
+```mermaid
+flowchart TD
+  Room[Room goal] --> Discussion[Proposals, critiques, and replies]
+  Room --> Task[Task and revisioned claim]
+  Task --> File[Project artifact and SHA-256]
+  File --> Accept[Operator acceptance]
+  Discussion --> Ack[Recipient acknowledgement]
+  File --> Ack
+  Accept --> Outcome[Recorded result and evidence]
+  Outcome --> Lesson[Candidate lesson and recorded evaluation]
+  Lesson --> Promote[Explicit promotion or rollback]
+```
+
+The browser and project-local MCP tools can read the same workroom, report outcomes, and resume from recorded state. Lessons record operator-supplied comparisons. Promotion requires a failed baseline, a passing candidate, and passing safety controls. Rollback archives the promoted memory’s retrieval influence. Native host loading and a live exchange should be checked in each selected host.
+
+![A real lesson evaluation with a recorded rollback](assets/7.1.4-hub-learning.png)
+
+## Inspect estimates and host evidence
+
+- **Context** builds a pack for the selected project and can compare adaptive and legacy retrieval. The estimates describe rendered context. Review the selected sources before copying.
+- **Models** shows local client skill-file checks and retained activity evidence. Model identity and provider counts stay unavailable.
+- **Usage** separates measured tool timing from explicit reports. Counts describe the retained journal loaded by this workspace. Context token estimates do not quantify provider charges.
+- **Setup** provides configuration recipes and live feature controls. A printed recipe or detected skill file does not establish that a host connected.
+
+![Classic Context Lab with explained retrieval](assets/7.1.4-context-lab.png)
+
+![Detailed activity diagnostics with replay](assets/7.1.4-replay.png)
+
+![Hub Setup with local feature switches and host recipes](assets/7.1.4-hub-setup.png)
+
+<img src="assets/7.1.4-hub-mobile.png" width="390" alt="Brain Hub on a 390 pixel mobile viewport">
+
+[Quickstart](QUICKSTART.md) · [Workspace guide](WORKSPACE.md) · [Features and limits](FEATURES_AND_LIMITS.md) · [Troubleshooting](TROUBLESHOOTING.md)
+
+