@theihtisham/agent-shadow-brain 7.2.0 → 7.22.1

package/docs/LEARNING.md

@@ -0,0 +1,46 @@
+# Learning from work
+
+Shadow Brain 7.1.4 can reuse project-specific feedback when assembling adaptive context. The loop is explicit: select relevant memory, do the task in the host, observe the result, report what helped or failed, and inspect the effect on later retrieval.
+
+```mermaid
+flowchart LR
+    A[Current task] --> B[Scoped adaptive context]
+    B --> C[Host performs authorized work]
+    C --> D[Observed outcome]
+    D --> E[Reported memory feedback]
+    E --> F[Bounded task-relevant adjustment]
+    F --> B
+    E --> G[User review / remove / disable]
+```
+
+The MCP tool assigns `reporter: agent`; portal and CLI feedback assign `reporter: user`. Neither reporter can claim its result is machine-verified by this system. Source and evidence references are not fetched. A tool call succeeding is not evidence that the task succeeded.
+
+## What changes in retrieval
+
+Feedback operates only on direct lexical candidates that passed normal project and curation filters. It cannot create a match, boost a graph-only neighbor, revive archived/contested/superseded memory, add source provenance, or alter stored memory content.
+
+The task matcher drops generic action words and compares substantive terms. A report needs at least one substantive overlap and a Jaccard similarity of at least 0.34 with the current query. Up to three recent matching distinct tasks contribute. The adjustment is the mean of each rating value multiplied by task similarity and reporter weight.
+
+| Input | Value |
+| --- | ---: |
+| Useful | +0.08 |
+| Not useful | -0.04 |
+| Incorrect | -0.12 |
+| User reporter weight | 1 |
+| Agent reporter weight | 0.5 |
+| Final adjustment bounds | -0.12 to +0.08 |
+
+The final score cannot go below zero. The candidate report exposes the signed **Project task feedback** signal, contributing record IDs, and reporter kinds. This is a ranking heuristic, not a confidence or truth score.
+
+An identical memory/task/reporter combination updates its prior record. When eligible exact-text duplicates are grouped, the newest report from each normalized task can contribute once, with user reports taking precedence over agent reports. Candidate details retain the contributing report IDs. The sidecar is limited to 500 records and 2 MiB, with bounded task, reason and evidence fields. At capacity, a new distinct record is rejected. Existing records can still be updated or removed. Changes use revision checks and atomic file replacement. No age expiry is silently imposed.
+
+## Keep control
+
+- Turn local learning influence off to retain records while restoring baseline adaptive scoring.
+- Remove a report to withdraw its influence.
+- Use normal memory curation to mark a claim contested or archive an outdated record. An `incorrect` report does not secretly change curation state.
+- Review agent reports against actual checks. A plausible explanation can still be wrong.
+
+This feature is limited to the explicit project workspace and matching local MCP/CLI store. Library callers opt in by passing a `ProjectFeedbackSnapshot` to `assembleContext`. Existing global-store retrieval and legacy profiles do not automatically adopt feedback.
+
+[Project Kit walkthrough](PROJECT_KIT.md) · [Retrieval evaluation](evaluation/CONTEXT_EVALUATION_v7.1.4.md)

package/docs/PROJECT_KIT.md

@@ -0,0 +1,98 @@
+# Project Kit: knowledge and skills for one workspace
+
+Project Kit combines a local knowledge store, bounded project inspection, task-specific skill generation, and feedback from actual work. Everything belongs to the selected project. Opening another project does not import these memories or install the skill globally.
+
+## 1. Open your project
+
+```bash
+shadow-brain project workspace .
+```
+
+Open the printed address and choose **Project Kit**. This mode needs no model provider and does not read coding-client profiles. Closing the portal keeps your saved files. The older `dash` command still opens the shared-store dashboard; it does not silently switch or merge stores.
+
+| File or folder | Purpose |
+| --- | --- |
+| `.shadow-brain/project-memory.json` | Explicit project knowledge |
+| `.shadow-brain/memory-annotations.json` | Reviews and recorded memory relationships |
+| `.shadow-brain/feature-settings.json` | Workspace runtime controls |
+| `.shadow-brain/activity-journal.json` | Bounded measured/reported activity metadata |
+| `.shadow-brain/memory-feedback.json` | Reported outcomes and local learning control |
+| `.shadow-brain/project-kit-skills` | Ownership receipts for generated skills |
+| `.shadow-brain/disabled-project-skills` | Verified disabled copies outside client discovery paths |
+| Selected host's project skill folder | Generated `SKILL.md` files |
+
+Files are created when their feature needs to save data. Treat knowledge and skill content as project files: decide what belongs in version control before sharing the repository. Moving a project changes its path-derived project ID; this release does not automatically reassign earlier memory IDs to the new location.
+
+## 2. Inspect what the project actually declares
+
+```bash
+shadow-brain project inspect .
+```
+
+Inspection reports observed stack markers, package-manager markers, and known check names. It scans at most 500 directory entries through depth three, with bounded allowlisted manifest reads. A script named `test` yields a suggested command; its body is not returned or executed. Lockfiles and configuration markers can identify a tool without reading their contents. The scanner skips linked paths, dependency/build trees and private configuration locations.
+
+These are observations, not complete semantic understanding. Missing manifests, a large monorepo, custom scripts, or an unfamiliar stack can leave gaps. The profile shows coverage and warnings. Check the suggested command before running it.
+
+## 3. Add knowledge you want the agent to retain
+
+Use the knowledge form for a project constraint, decision, rule, or known lesson. An optional reference records where you found it; the service does not fetch that reference or certify the statement.
+
+```bash
+shadow-brain project knowledge . --title "Checkout retry contract" --content "Preserve the original idempotency key across retries." --source "docs/checkout.md"
+```
+
+The command returns the committed memory ID and project ID. The original text is stored with explicit user provenance. A reference is recorded only when you supply one, so adding a note without a source does not inflate source coverage.
+
+Open **Context Lab**, select the project, and ask about checkout retries. The saved note is immediately available to scoped retrieval. You can inspect, contest, archive, or connect it through the existing memory tools.
+
+## 4. Turn a requirement into a local skill
+
+Describe the task, choose a client, and optionally supply knowledge. **Use in skill** reuses the knowledge you just added. Preview shows the exact destination and Markdown before Apply.
+
+```bash
+shadow-brain project skill . --target codex --name checkout-retries --requirement "Fix checkout retries and verify that each request commits once."
+```
+
+The output includes `planHash`. Repeat the same inputs with `--apply --expected-plan-hash HASH_FROM_PREVIEW` to write the reviewed plan. The generated skill includes your requirement, supplied knowledge, observed project evidence, and relevant declared checks. It is deterministic; no model or install script runs during generation.
+
+| Client target | Generated path |
+| --- | --- |
+| `codex` | `.agents/skills/NAME/SKILL.md` |
+| `claude-code` | `.claude/skills/NAME/SKILL.md` |
+| `opencode` | `.opencode/skills/NAME/SKILL.md` |
+| `deepseek-harness` | `.dsh/skills/NAME/SKILL.md` |
+| `portable` | `.agents/skills/NAME/SKILL.md` |
+
+Apply recomputes the preview, checks path safety and ownership, and refuses stale plans or files that were edited outside Project Kit. An unowned file is not overwritten, even if its name matches. Generated skills do not edit `AGENTS.md`, provider settings, or global skill directories. Host support and skill discovery still need to be checked in the client.
+
+In **Setup → Managed project skills**, preview Disable, Enable, or Remove to see the affected paths. Disabling moves the verified `SKILL.md` bytes into the workspace’s disabled-skill folder. Enabling restores them only when the discovery path is free. Removal deletes the verified file and its Project Kit receipt. Supporting files and other skill installations stay in place.
+
+The panel reports edited files, destination conflicts, and pending operations. For a pending operation, review the same action to complete it. Reload the coding client to refresh its skill discovery. An existing chat can still contain instructions it loaded earlier.
+
+## 5. Connect the same local knowledge to your agent
+
+```bash
+shadow-brain project config . --target codex
+```
+
+Merge the printed recipe into the selected host's configuration. It includes the explicit project directory, project ID and local `--db` path. The connected MCP process then reads the same knowledge shown by the portal.
+
+The local launch adds `project_inspect`, `project_knowledge`, `project_skill_preview`, `project_skill_apply`, and `project_feedback` to the regular memory tools. Preview/apply is a two-step operation. Saved text and observations remain reference material; they do not override current user instructions or the host's permissions.
+
+## 6. Learn from reported outcomes
+
+After a real task, record whether a selected memory helped. The **Memory outcomes** panel keeps the task, outcome, reason, optional evidence labels and reporter visible. A user report and an agent report remain distinguishable. Agents can call `project_feedback` after observing a concrete result; retrieval alone never creates positive feedback.
+
+```bash
+shadow-brain project feedback list .
+shadow-brain project feedback record . --memory MEMORY_ID --task "Fix checkout retries" --rating useful --reason "The existing idempotency contract matched the passing retry regression check." --evidence "tests/checkout-retry.test.ts"
+shadow-brain project feedback set off --project .
+```
+
+Use `useful`, `not-useful`, or `incorrect`. Record only an outcome you observed; the example reason is not a claim that your tests passed. Feedback is reported evidence, not an automatic truth verdict. The portal lets you remove a record or disable its influence while keeping the history available.
+
+Adaptive retrieval applies a small signed adjustment only when the memory already matches the current task and the feedback task is relevant. Repeated identical reports are updated instead of counted again. User reports carry more weight than agent reports. Context Lab shows the applied signal and links to reported outcomes; diagnostic JSON retains record IDs. Legacy retrieval, unrelated projects, inactive memories, and empty-query browsing do not gain feedback influence.
+
+This improves local reuse through outcome feedback. It does not train model weights, verify external sources, execute self-modifying code, or guarantee that an agent's next answer will be correct. [Learning rules and limits](LEARNING.md)
+
+[Client integration](INTEGRATIONS.md) · [Context Lab](CONTEXT_LAB.md) · [Workspace guide](WORKSPACE.md)

package/docs/QUICKSTART.md

@@ -0,0 +1,62 @@
+# Quickstart
+
+This guide covers the 7.22.0 Brain Hub. Use Node.js 22.13 or later in the 22.x line, 24.x, or 26 and later.
+
+## Install and open a project
+
+From the project directory, you can start with one command:
+
+```bash
+npx --yes --package @theihtisham/agent-shadow-brain@7.22.0 shadow-brain project workspace . --port 62595
+```
+
+Or install the reusable CLI:
+
+```bash
+npm install -g @theihtisham/agent-shadow-brain@latest
+shadow-brain --version
+cd your-project
+shadow-brain project workspace . --port 62595
+```
+
+Check that the CLI prints `7.22.0` for these steps. Keep the command running and open [the Brain Hub](http://127.0.0.1:62595/hub). The process writes project data inside the selected project’s `.shadow-brain` directory. On restart, run the same command from the same project directory. If you use `--port 0`, open the URL printed by the current process.
+
+From a source checkout, use `npm ci` and `npm run build`, then replace `shadow-brain` with `node dist/cli.js` from the checkout. Pass the intended project directory as the workspace argument.
+
+![Running Brain Hub control room](assets/7.22.0-hub-graph.png)
+
+## Save a fact in ordinary words
+
+1. Open **Knowledge** and type “The cupboard is black. Keep its brass handles.”
+2. Click **Add to memory**. No title, JSON or upload is required.
+3. Open **Context** and ask “What colour is the cupboard?” The returned reference includes your note and a link to its original text.
+4. Connect your chosen host through **Setup** so it can retrieve the same memory through MCP.
+
+For longer notes, choose **Review first** and save the useful parts. Optional PDF and JSON imports stay available below the plain-text form. Image-only PDFs need OCR, which is not included.
+
+![Approved source page and extracted citation](assets/7.1.4-hub-knowledge.png)
+
+## Connect a host
+
+```bash
+shadow-brain project config . --target codex
+shadow-brain skills install . --target codex
+```
+
+Merge the recipe into the selected host’s configuration. Preview the skill-file changes, then use `--apply` if you want them. Reconnect the host and confirm it can call a tool such as `project_inspect` or `context_pack`. Host file presence, recorded activity, and model evidence are shown separately. [Supported client recipes](INTEGRATIONS.md)
+
+## Explore shared work
+
+Create a room in **Collaboration**, add a task, and record a proposal or critique. A participant can claim the task, attach a project-relative artifact, and record a result. **Learning** turns recorded outcomes into candidates with explicit evaluation and promotion. [Workspace guide](WORKSPACE.md)
+
+The classic workspace at `/workspace` provides detailed memory review, context selection, and retrieval feedback. `/live` opens the detailed journal. `shadow-brain demo workspace --port 0` runs a separate synthetic tour.
+
+[Visual guide](VISUAL_GUIDE_v7.22.0.md) · [Troubleshooting](TROUBLESHOOTING.md)
+
+## Plain-language notes, sessions, and live files
+
+In **Knowledge**, paste ordinary notes or a plan and choose **Add to memory**. Direct saving accepts 6,000 characters and 20 paragraphs; **Review first** handles longer notes. **Context** lets you try a task, inspect original evidence, and compare a focused context pack with a bounded reference under the same project controls. **Learning** records usefulness feedback.
+
+Open **Sessions** for explicitly reported conversation history and saved handoffs. A connected host can call `session_open`, record meaningful progress, and create a checkpoint; another host calls `session_resume` with that checkpoint to continue. Imported transcripts are deliberate snapshots, not automatic access to native private chat history. [Sessions guide](SESSIONS.md).
+
+In **Setup**, choose sharing preferences, context ceilings and optional **project file activity**. A filesystem event does not identify its author. Pushed updates need the local server to remain running. Tool participation applies to cooperating client labels; it does not configure or control another application globally.

package/docs/README.md

@@ -0,0 +1,36 @@
+# Agent Shadow Brain documentation
+
+Agent Shadow Brain 7.22.0 provides a local workspace, CLI, and standalone MCP service for project memory, task context, and generated project skills.
+
+## Start and use the workspace
+
+| Guide | Use it to |
+| --- | --- |
+| [Source intake](SOURCE_INTAKE.md) | Paste notes, review corrections, import simple conversations and inspect original evidence. |
+| [Visual guide](VISUAL_GUIDE_v7.22.0.md) | See actual browser captures and their fixture provenance. |
+| [Quickstart](QUICKSTART.md) | Install the exact version, launch the synthetic demo, and open your project workspace. |
+| [Project Kit](PROJECT_KIT.md) | Inspect one project, save local knowledge, and preview and apply a tailored skill. |
+| [Context Lab](CONTEXT_LAB.md) | Assemble, inspect, compare, and copy a task brief. |
+| [Reported outcomes](LEARNING.md) | Record an observed result and inspect, pause, or remove its bounded influence on later retrieval. |
+| [Workspace guide](WORKSPACE.md) | Review memory, work with typed links, check project health, and follow recorded activity. |
+| [Features and limits](FEATURES_AND_LIMITS.md) | Distinguish implemented behavior from host prerequisites, estimates and unavailable metrics. |
+| [Client integrations](INTEGRATIONS.md) | Configure MCP stdio, inspect project skill files, and understand which surfaces the client exposes. |
+| [Workflow skills](WORKFLOW_INTEGRATION.md) | Preview or install the six focused project skills. |
+| [Showcase](SHOWCASE.md) | See Project Kit, Context Lab, memory review, outcome feedback, and Live replay with synthetic data. |
+
+## Architecture and evidence
+
+- [Component guide](COMPONENTS.md) maps the shared paths and retained modules.
+- [Agent memory approaches](COMPARISON.md) compares the documented architectures and tradeoffs of related systems.
+- [Paired retrieval evaluation](evaluation/CONTEXT_EVALUATION_v7.1.4.md) reports 14 author-generated diagnostic cases against both profiles. [Raw results](evaluation/CONTEXT_EVALUATION_v7.1.4.json)
+- [Research and acceptance plan](launch/RESEARCH_AND_PLAN_v7.22.0.md) records the research, implementation scope, and verification gates.
+
+## Release and support
+
+- [7.22.0 release notes](launch/RELEASE_NOTES_v7.22.0.md) cover shared sessions, native history, project controls and compatibility.
+- [Verification record](launch/RELEASE_ACCEPTANCE_v7.22.0.md) separates tested behavior, local measurements and native-client coverage.
+- [Changelog](../CHANGELOG.md) · [Historical versions](versions/README.md) · [7.0 migration notes](launch/RELEASE_NOTES_v7.0.0.md)
+- [Troubleshooting](TROUBLESHOOTING.md) covers installation, storage, context, and local activity checks.
+- [Open an issue](https://github.com/theihtishaam/agents-brain/issues) with the version, reproduction steps, and relevant diagnostics.
+
+[Project README](../README.md)

package/docs/ROADMAP-v7.md

@@ -0,0 +1,147 @@
+# Shadow Brain — Roadmap to v7.0 and Beyond
+
+> **Status:** Living document
+> **Last updated:** 2026-05-12
+> **Author:** @theihtisham
+> **Companion docs:** `RELEASE_NOTES_v6.0.2.md`, `VIRAL-PLAYBOOK.md`
+
+This is the strategic plan. v6.0.2 ("Singularity") shipped the substrate. v7.0 is where Shadow Brain becomes the default infrastructure for every AI coding agent on Earth.
+
+---
+
+## North Star
+
+> **"Every line of code an AI agent writes anywhere should be able to draw on every relevant lesson your team has ever learned — instantly, locally, privately."**
+
+That's it. The roadmap exists to compound toward that.
+
+---
+
+## v7.0 — "Multiplayer" (target: Q3 2026)
+
+The theme is *plurality*. v6 made the brain smart; v7 makes it social.
+
+### 🟥 Tier-S (no v7 without these)
+
+#### S1. CRDT real-time team sync (Yjs)
+Replace `team-sync` JSON-stomp protocol with **Yjs**. Two engineers on the same brain, concurrent edits, conflict-free. Figma-for-knowledge.
+- Yjs Y.Doc per project
+- WebSocket relay (default: free, self-hosted) + optional Cloudflare relay
+- Encrypted-at-rest via existing `brain-encryption.ts`
+- Backwards-compat shim for v6 team-sync clients
+
+#### S2. VS Code Marketplace launch
+The repo has `vscode-extension/` — it's not on the marketplace yet.
+- Inline memory highlights ("Agent X learned this from file Y")
+- Hover for entity provenance ("learned 2 weeks ago by Cursor, confirmed 3× by Claude")
+- One-click "ask brain about this function"
+- Codelens for files: "12 brain memories · 3 ADRs · 1 collision pending"
+- Status bar: brain health · forgetting curve · last sync
+- Publisher account: needs theihtisham@ Microsoft Partner Center setup
+
+#### S3. SWE-Bench-Verified public leaderboard
+v6.0.2 shipped the harness. v7 runs it for real.
+- 50-problem SWE-Bench-Verified subset
+- Brain off vs brain on for: Claude 4.7, GPT-5, DeepSeek V3, Llama 4
+- Published dashboard at `brain.dev/leaderboard` (domain TBD)
+- Numbers become the marketing — if brain delivers +20pp resolution, that's the headline
+
+#### S4. Brain Exchange seeded with 10 canonical packs
+The marketplace exists; the content doesn't. Pre-build and curate:
+- React 19 · Next.js 16 · Vue 4 · Svelte 6
+- Django 5 · Rails 8 · FastAPI · NestJS
+- Rust async (Tokio/axum) · Solidity · Unity 6
+- K8s ops · Postgres ops · Solana programs
+Each pack: 200-500 high-signal entities, signed, MIT-licensed.
+
+### 🟧 Tier-A (high impact)
+
+#### A1. Mobile companion (React Native + Expo)
+"Brain in your pocket."
+- Voice capture: hold-to-talk → transcribe → ingest as memory
+- Photo capture: snap a whiteboard → llava → memory entity
+- Dashboard read-only view
+- Notifications: "Your brain forgot X yesterday — restore?"
+- Syncs via team-sync (Yjs)
+
+#### A2. Multimodal v2 — real OCR + diagrams
+v6.0.2 stubs OCR. v7 wires tesseract-wasm (zero install) for clean text extraction. Plus diagram parsing (Mermaid/PlantUML detection).
+
+#### A3. Project-LoRA — actually trained
+v6.0.2 ships the pipeline. v7 actually trains + publishes:
+- 5 reference adapters on Hugging Face (one per canonical brain pack)
+- Per-user trained adapters via paid tier (compute pass-through, no margin)
+- Ollama Modelfile auto-generation
+- A/B vs base model in eval harness
+
+#### A4. Constitution v2 — auto-evolution
+v6.0.2 reads `constitution.md` statically. v7 lets the brain **propose new rules** when it sees repeated violations of patterns. User approves → rule added. Living constitution.
+
+#### A5. Time-travel UI in dashboard
+Brain Replay is currently CLI/SVG. v7 ships an interactive React panel: drag-scrub, play, slow-motion, jump-to-milestone, full-screen.
+
+### 🟨 Tier-B (high-leverage smaller bets)
+
+- **B1.** Brain Exchange CLI commands: `shadow-brain exchange install react@latest` → ready in 5 seconds
+- **B2.** Pricing tier signal: free → pro ($10/mo for team sync relay + LoRA training compute)
+- **B3.** Public homepage: `brain.dev` (or `shadow-brain.dev`) with live demos
+- **B4.** SDK in 3 langs: TypeScript (have it), Python, Rust — for embedding brain in any tool
+- **B5.** "Ask the Hive" public demo — drop in a code snippet on the homepage, see the brain answer live (with rate limit)
+- **B6.** Cursor / Cline / Aider plugins-on-their-marketplace (where they have one)
+- **B7.** GitHub Action: `shadow-brain/learn-from-pr@v1` — every merged PR ingests its lessons
+- **B8.** Brain garden v2 — actual knowledge-graph editor, not just a viz
+
+### 🟩 Quality of life (do anytime)
+
+- 30-second `demo` enhancements: add 3 themed sample projects (React, Django, Rust) the user can pick
+- Per-platform installers: Homebrew tap, scoop, winget
+- One-click migration from Cursor/Cline-stored prompts (if those tools expose any local memory)
+- Brain "health report" weekly email (opt-in)
+- "What did my brain learn today?" daily digest
+
+---
+
+## v7.5 — "Distributed" (target: Q4 2026)
+
+### Big swings
+
+- **Federated brains** — multiple teams' brains can selectively share concepts without merging fully. Cross-org learning without leaks.
+- **Constitution federation** — share rules across projects with diff-and-approve flow
+- **Real-time co-debugging** — two engineers + their brains + shared cursor on a bug, with hive-voice for decisions
+- **Brain forking** — `shadow-brain fork --from theihtisham/react-pack` like GitHub for brains
+- **Brain pull requests** — propose a change to a public brain, peer-reviewed
+
+---
+
+## v8.0 — "Self-Aware" (target: 2027)
+
+The brain becomes meta-cognitive.
+
+- **Self-tuning forgetting curve** — brain decides what to keep based on observed agent behavior, not heuristics
+- **Brain self-debugging** — brain detects its own degraded recall and proposes interventions
+- **Cross-brain federated learning** — multi-team adapters fine-tuned across consenting brains, privacy-preserving (DP-SGD or LoRA federation)
+- **Predictive memory** — brain pre-fetches likely-needed memories *before* the agent asks, based on session trajectory
+- **Brain handoff to humans** — handoff briefing generator: when a human takes over from an agent, get a one-page "what the agent thinks it knows + what it's uncertain about"
+
+---
+
+## What we will NOT build
+
+Explicit anti-list. Saves time arguing.
+
+- **Hosted-only SaaS shell** — defeats the local-first thesis. Always local-first; cloud is a relay, not a brain.
+- **Closed core, open shell** — the brain stays MIT. Always.
+- **LLM provider lock-in** — must work with Ollama / vLLM / any OpenAI-compat / Anthropic API equally.
+- **Replacing the agent** — Shadow Brain is *for* agents, not a competing agent. Hermes-Devin-AutoGen territory is theirs.
+- **Surveillance features** — no telemetry. No "anonymous usage data." Ever.
+
+---
+
+## How to push back on this roadmap
+
+This document changes. File an issue at `github.com/theihtisham/agent-shadow-brain/issues` with:
+- The item you disagree with
+- What you'd do instead
+- Why (with evidence — your team's experience, paper citation, etc.)
+
+Strongest arguments win. The author reserves the right to be wrong publicly.

package/docs/SESSIONS.md

@@ -0,0 +1,77 @@
+# Shared project sessions
+
+Run the local Hub from your project and generate a recipe for each coding agent you use.
+
+```bash
+shadow-brain project workspace . --port 62595
+shadow-brain project config . --target codex
+```
+
+Use `claude-code`, `opencode`, or `deepseek-harness` for the other native recipes. Configure each host to use its recipe from the same project directory, then confirm `session_list`, `session_read`, `session_checkpoint_read`, `session_open`, `session_record`, and `session_resume` appear in its MCP tool list. Open **Sessions** in the project Hub to review work reported by those clients. [Client setup](INTEGRATIONS.md)
+
+## Track work and continue with another agent
+
+1. At the start of shared work, call `session_open` with a title, the project goal, and an operation key. Supply `hostSessionId` when the host already has a safe conversation label to share. A child worker can set `parentSessionId` to the UUID of an existing project session.
+2. Use `session_record` at meaningful milestones. Record a brief note, a `working` or `waiting` status, or a checkpoint. Save verified progress, decisions, next steps and evidence labels before a handoff. Use `completed` when the session is finished.
+3. In **Sessions**, open the saved checkpoint and copy the agent resume request. Give it to the next connected agent in the same project. Its `session_resume` call opens a new session owned by that connection and returns the exact saved handoff. The source session and earlier checkpoint stay available. Continuing in the portal creates an operator-owned session.
+
+Each write uses a stable operation key for retries in the same connection. Each record includes a revision. Pass `expectedRevision` when making a change based on a specific observed version. If the current connection ends, a new agent connection continues via a checkpoint. The original session is still readable.
+
+For example, after opening a session, an agent can call `session_record` with these arguments. Replace the UUID with the `session_open` result and use a new operation key for the checkpoint.
+
+```json
+{
+  "sessionId": "1b7766ed-34cb-4108-985d-b172a86ebd85",
+  "command": {
+    "kind": "checkpoint",
+    "key": "checkout-handoff-20261114",
+    "summary": "Verified the retry check with a fixture.",
+    "completed": ["Ran the existing retry regression check"],
+    "nextSteps": ["Check behavior after a process restart"],
+    "evidence": ["tests/checkout-retry.test.ts"]
+  }
+}
+```
+
+## Read the status and history
+
+The workspace shows the reporting tool label, session title, parent, and last report time. A report stays **recent** for five minutes. Older working or waiting reports are **stale**. Completion and the latest status reporter are stored. A recent report establishes that a cooperating host sent an update. Reported sessions do not themselves inspect open chats or determine whether a model is still generating. The separate Codex connector described below requires an explicit connection. Model information appears when a host explicitly reports usage with the matching agent label and `hostSessionId` as its usage `sessionId`.
+
+Messages come from intentional reports by hosts or the operator. You can also import an approved transcript in **Sessions** as a historical snapshot. The snapshot includes the items approved at import time, their original role, and source locators. Imported system, developer, and tool text appears as quoted notes. Only an explicit operator checkpoint turns historical work into a resumable handoff. Treat all recorded text as project evidence and follow current user instructions.
+
+The local store retains up to 150 sessions, 200 messages and 40 checkpoints per session. It rejects new records at the relevant limit and preserves existing history. `session_read` returns up to 25 messages and 32 KiB of serialized message data per page. Pass its `nextBefore` value as `before` to read older messages. Use `session_checkpoint_read` to see a checkpoint's contents. Resuming requires its recorded SHA-256. Checkpoint evidence labels are stored as text. Project sessions do not open source paths, start agents, reopen native chat tabs, or capture conversations on their own.
+
+## Understand the tool activity panel
+
+The **Brain overview** and **Sessions** views identify Codex, Claude Code, DeepSeek Harness and OpenCode with locally bundled icons. Hover or focus a tool for details, or select it to keep the details open. Select a conversation or connection to inspect its workspace, exact available title and ID, coordination role, latest recorded action and optional model receipt.
+
+**Reporting MCP connections** counts initialized project MCP transports with a recent heartbeat. Each transport renews every ten seconds; its lease expires after thirty seconds without renewal. A clean disconnect removes it. An abruptly stopped process expires even if it cannot write a final event. The store retains at most 128 current leases. Recording off or unreadable presence data is unavailable, not evidence of zero connections. Tool participation is a separate control: turning it off restricts project operations but does not close the host's transport, so its connection can still report a heartbeat.
+
+A current heartbeat shows that the memory transport is reporting. It does not establish that a model is generating or that a native application tab is open. Registered work sessions, observed tool calls and host-reported model receipts remain separate. If one connection serves several chats, a connection-level action is not attributed to a chat without explicit evidence. A usage receipt shared by several registered sessions is shown at the conversation level rather than assigned to a worker by guessing.
+
+Model, provider, effort and token counts appear only when explicitly reported. These receipts do not prove a proxy's underlying model. Fresh journal events can briefly animate the activity indicator; heartbeat renewals do not animate work or reload the graph. Pause motion and reduced-motion preferences keep the interface still.
+
+## Connect to Codex project history
+
+In **Sessions**, select **Connect installed Codex**. This starts a separate, read-only local Codex app-server connection for the project open in the Hub. Nothing is connected or read until you select this control. The connector uses the installed CLI; it does not start a model, create a native conversation, read browser data, or request authentication information. Select **Disconnect Codex** to close the connection. It expires automatically after 15 minutes.
+
+The connector asks Codex for its indexed current conversations whose recorded working directory matches this project. Use **Show archived chats** for a separate archived list and use the page controls to browse further. The index-only query avoids asking Codex to scan and repair rollout files, so the list can omit conversations that have not appeared in its state index. It is not a guarantee of complete native history. The exact title is shown when Codex provides one; otherwise the Hub says the original title is unavailable. The native conversation ID and its separate session-group ID are not interchangeable.
+
+Select a conversation to read a bounded page of visible user and assistant text, then use **Earlier history** for older pages. The page shows how many non-text or unsupported items were omitted. Tool output, reasoning, and attachments are not imported as messages. To keep the displayed page in shared project sessions, select **Save this history page**. The Hub verifies the page fingerprint before saving; if the source changed, review the new page first. A saved page is an immutable, possibly partial snapshot. It is not automatically added as project knowledge and does not resume the original native chat.
+
+While **Sessions** is open and connected, the Hub checks the current list every ten seconds and reloads the selected page when its reported update timestamp changes. This does not automatically save new snapshots. The timestamp is supplied by the separate app-server and can have limited resolution; its runtime state does not prove whether a desktop chat is active. The connector requires a compatible app-server with bounded history paging. On Windows it looks for the official npm package's local vendor executable; custom installation locations may not be detected. See the [Codex app-server protocol](https://learn.chatgpt.com/docs/app-server).
+
+## Import a native conversation export
+
+In **Sessions**, choose the originating tool and one exported conversation. The Hub keeps the exact title when the export provides one. When the original workspace is recorded, it must match the open project. Selected exports are saved as separate historical snapshots, with their original conversation ID and source fingerprint. The same export reopens the original snapshot. A changed export links a new snapshot to the previous one. Imports do not create memories or run instructions in the conversation.
+
+| Tool | Accepted export | Title source |
+| --- | --- | --- |
+| Codex | Selected rollout JSONL or a `codex-rollout-v1` JSON wrapper | The matching `thread_name` in the supplied session index entry. A rollout by itself may have no name. |
+| Claude Code | Selected main conversation JSONL or a `claude-agent-sdk-v1` JSON wrapper | Latest custom title for that conversation. SDK summaries are separate from custom titles. |
+| OpenCode | V1 or V2 session JSON from `opencode session export <id> --sanitize` | The exported session's `info.title`. |
+| DeepSeek Harness | Canonical V4 JSONL or the selected ZIP containing one root session log | Latest title event in the exported conversation. Child logs and attachments stay outside this import. |
+
+Codex wrappers include `format`, the selected `rollout` as a JSONL string, and `sessionIndex` with the matching name record. Claude SDK wrappers include `format`, a `session` from `listSessions`, and `messages` from `getSessionMessages` for that session. Choose the one workspace and conversation you intend to share. [Codex session index source](https://github.com/openai/codex/blob/main/codex-rs/rollout/src/session_index.rs) · [Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/typescript) · [OpenCode commands](https://opencode.ai/docs/cli/commands/) · [DeepSeek archive source](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/session-query/session-log-export/src/archive.ts)
+
+Imports accept up to 2 MiB and retain visible user and assistant text with its source locators. Tool arguments, reasoning blocks, system messages, and attachments are excluded. Select only exports you intend to share with this project. An imported session can be continued after the operator saves a handoff checkpoint.

package/docs/SHARING.md

@@ -0,0 +1,13 @@
+# Share Agent Shadow Brain
+
+## Short announcement
+
+> Agent Shadow Brain 7.1.3 gives coding clients a shared local store for project decisions and lessons. Build a scoped context pack, review the memories behind it, and follow measured MCP calls in the live portal. Project skills and local MCP setup are available for Codex, Claude Code, OpenCode, and DeepSeek Harness.
+
+[GitHub repository](https://github.com/ihtishaam-dev/agent-shadow-brain) · [7.1.3 release and recording](https://github.com/ihtishaam-dev/agent-shadow-brain/releases/tag/v7.1.3) · [npm package](https://www.npmjs.com/package/@theihtisham/agent-shadow-brain/v/7.1.3) · [Client setup](INTEGRATIONS.md)
+
+## Demo caption
+
+> Scripted local clients run real MCP calls against synthetic project memories. The live portal shows measured tool timing and marks explicitly reported task phases.
+
+[Live screenshot](assets/live-v7.1.3.png) · [Workspace showcase](SHOWCASE.md)

package/docs/SHOWCASE.md

@@ -0,0 +1,87 @@
+# Workspace showcase
+
+The images show the 7.1.4 workspace with synthetic projects, memory records, reviews, and links. The Project Kit images use a separate persistent synthetic project. The live views use scripted local MCP calls. Displayed phases come from explicit reports, and durations come from measured calls in that demo.
+
+```bash
+shadow-brain demo workspace --port 0
+```
+
+Open the printed **Workspace** or **Live view** address. Use `--no-activity` for a fixed initial journal snapshot.
+
+## Project Kit
+
+In a project-local workspace, inspect observed stack markers and declared checks. Save a knowledge record and use it when drafting a skill for the selected client.
+
+![Project Kit showing observed stack evidence and local knowledge controls](assets/7.1.4-project-kit.png)
+
+Review the generated `SKILL.md` and its destination before applying it. The preview includes the user-supplied requirement and available checks.
+
+![Generated project skill preview with the target path and Markdown](assets/7.1.4-project-skill-preview.png)
+
+### Reported memory outcomes
+
+Record an observed result with a task, rating, reason, and optional references. The saved card shows the reporter and gives the user a way to remove the report. The switch controls whether later adaptive retrieval can use the reports.
+
+![Project Kit with a user-reported useful outcome and an influence toggle](assets/7.1.4-learning.png)
+
+The next matching task shows the report's signed contribution alongside the other ranking signals.
+
+![Context Lab showing a positive Project task feedback contribution and user attribution](assets/7.1.4-outcome-ranking.png)
+
+## Overview and attention queue
+
+Choose the project scope, review source coverage, and open a record from the attention queue. The queue flags conditions that merit inspection, including contested records and missing references.
+
+![Overview and the project memory attention queue](assets/7.1.4-overview.png)
+
+## Context Lab
+
+Assemble a brief, check its estimated tokens and rendered characters, then expand a candidate to see matched fields, ranking contributions, or a recorded link path.
+
+![Context Lab with task settings, brief metrics, and retrieval stages](assets/7.1.4-context-lab.png)
+
+### Compare profiles
+
+Compare the same task and scope with Adaptive and Legacy. The result lists which memories each profile adds and shows their estimated usage.
+
+![Adaptive and legacy comparison for the same task](assets/7.1.4-comparison.png)
+
+## Memory review and graph
+
+Inspect a saved record, its recorded references, and manual review controls. A review change is recorded in revision history.
+
+![Memory inspector with saved content, references, and review controls](assets/7.1.4-memory-review.png)
+
+Select an edge or focus the recorded relationships around one memory. The workspace distinguishes these relations from project membership and recording-agent links.
+
+![Focused graph showing recorded memory links and the inspector](assets/7.1.4-graph.png)
+
+## Integrations and features
+
+Read the documented capabilities and generate a setup example for the client. A project skill-file check and a live client handshake provide different evidence.
+
+![Integration cards and local diagnostics](assets/7.1.4-integrations.png)
+
+Choose when context, session briefings, and activity are available. The workspace keeps activity visibility and journal recording as separate controls.
+
+![The five runtime feature controls](assets/7.1.4-features.png)
+
+## Live operations and recorded replay
+
+Select a session or event to inspect the available history. The session network, timeline, and charts distinguish measured tool activity from explicit host reports.
+
+![Live operations with the session network and measured timing](assets/7.1.4-live.png)
+
+Replay navigates the loaded journal slice. Move to an event with the slider or step controls and return to the live stream when finished.
+
+![Journal replay controls over recorded events](assets/7.1.4-replay.png)
+
+![Animated capture of scripted local MCP activity and replay](assets/live-v7.1.4.gif)
+
+## Mobile layout
+
+Use the workspace on a narrow viewport to inspect the same saved records and context.
+
+![Workspace at a mobile viewport](assets/7.1.4-mobile.png)
+
+[Project Kit guide](PROJECT_KIT.md) · [Context Lab guide](CONTEXT_LAB.md) · [Workspace guide](WORKSPACE.md) · [Client integrations](INTEGRATIONS.md)

package/docs/SOURCE_INTAKE.md

@@ -0,0 +1,33 @@
+# Teach the project from your own notes
+
+Open **Knowledge**, write ordinary text and click **Add to memory**. For example: “The cupboard is black. Keep its brass handles.” The project is fixed by the workspace you opened. In **Context**, ask “What colour is the cupboard?” to inspect the retrieved fact and its original source. Connected agents can request the same project context through MCP.
+
+Direct saving supports up to 6,000 characters and 20 paragraphs. It preserves the original text and saves each paragraph as reference knowledge. Retrying the same note reuses the same records; earlier approved corrections remain intact. Previously skipped parts are not silently approved. No title, file or special format is needed, and no model is trained by saving a note.
+
+For longer notes or a correction before saving, choose **Review first**. Optional uploads support `.txt`, `.md`, `.json` and the separate PDF workflow. Ordinary text is the main path; files and JSON are optional.
+
+A preview splits plain text into paragraphs and displays their original lines. The title comes from the first nonblank line; a simple keyword rule suggests a category such as requirement, plan, or knowledge. These are suggestions, not an AI interpretation. Read each item, change its title, text, or category if needed, and approve or reject it. Approved text becomes project memory and may be used in later context. Pending and rejected items are not added as memories. Corrections take effect when you approve the corrected wording; this changes recorded context and does not train model weights.
+
+Previewing a valid source saves its original bytes, digest, filename, and review items in the project-owned source store even before approval. A second upload of identical bytes reopens the same review. The evidence view shows the original text and location alongside your approved wording; it verifies the stored relationship, not whether the claim is true. Do not include information you do not want saved in the project. The app does not read a browser's history, session data, or private client configuration to perform an import. Structured credential-shaped fields are rejected, but free-text secret detection is not comprehensive.
+
+Text and Markdown must be UTF-8 and are limited to 1 MiB, 500 sections, 6,000 characters per section, and 180,000 extracted characters in total. Break long paragraphs into smaller ones before importing. Text PDFs use the separate PDF page-review workflow and its limits; scanned/image-only PDFs require OCR, which this workflow does not provide.
+
+JSON accepts the following three versioned or simple interchange formats, plus an array of messages. Each content value must be a string. Unsupported nested exports, attachments, multimodal content, and unknown fields are rejected instead of silently omitted. System and developer roles in an imported transcript are quoted source evidence only; they do not become instructions to the app or an agent.
+
+```json
+{"schemaVersion":1,"kind":"knowledge","title":"Project notes","records":[{"title":"Build command","content":"Run the build before release.","source":"README.md"}]}
+```
+
+```json
+{"schemaVersion":1,"kind":"transcript","title":"Review discussion","messages":[{"role":"user","content":"Preserve Unicode."},{"role":"assistant","content":"The proposed constraint is to preserve Unicode."}]}
+```
+
+```json
+{"messages":[{"role":"user","content":"Preserve Unicode."}]}
+```
+
+Source labels such as `README.md` are citations only and are not opened. No import makes claims in a note true or independently verifies them. Review and correct the text before approving it.
+
+## Save a reviewed transcript as session history
+
+After reviewing a transcript, select **Open reviewed history in Sessions**. This creates a completed session containing only the messages approved at that time, preserving their original speaker labels and source locations. Messages labelled system, developer, or tool remain untrusted quoted notes. Repeating the import opens the existing snapshot; review all desired messages before the first import. No summary is generated automatically. You may write a checkpoint yourself and share its resume request with another connected project host. A portal continuation creates a portal-owned record, not a running model or a native host conversation.