Skip to main content
Glama

Running Brain Hub with stored synthetic project records and measured MCP calls

What works and its limits

The Brain Hub brings reviewed notes, cited documents, shared work, and recorded tool activity into one local workspace. This recording uses an isolated synthetic test project: 580 stored memories, a bounded graph view, and real MCP calls from scripted clients. It does not show a model's private thoughts or a customer's activity. Visual guide · Research and release plan

Try it

Use Node.js 22.13+ in the 22.x line, 24.x, or 26+. From your project directory, one command installs the requested version in npm's cache and starts its local portal:

npx --yes --package @theihtisham/agent-shadow-brain@7.22.2 shadow-brain project workspace . --port 62595

For a reusable global command:

npm install -g @theihtisham/agent-shadow-brain@latest
shadow-brain --version
cd your-project
shadow-brain project workspace . --port 62595

Keep the launcher running and open the project Brain Hub. Start with Knowledge → Add to memory, then Context → Find useful context. Connect your chosen tool through Setup when you want it to retrieve that memory. Use the same project directory and port when restarting. Port 0 lets the OS assign a free port; open the URL printed by that launch.

To build from this checkout while preparing a release, use npm ci, npm run build, then node dist/cli.js project workspace . --port 62595. The command’s directory argument selects which project store to open. Quickstart · Troubleshooting

Related MCP server: prelude-context

Inside the Brain Hub

Running Brain Hub with tool icons, selectable reported workers, model details and a stored memory graph in an isolated test workspace

View

What you can do

Brain overview

Recognize your tools by their icons, inspect reported agents and models, follow stored memory relationships, and seek through recorded activity. An empty store has zero graph nodes and edges.

Knowledge

Paste ordinary text and click Add to memory. Review longer notes, inspect original sources, or optionally import a document. Generate a project-specific skill.

Sessions

Inspect reported work, original conversation snapshots, saved checkpoints and linked continuations. Connect the supported Codex history API explicitly or select an export from another tool.

Collaboration

Open a project room, post a proposal or critique, claim a task, attach a project file, accept evidence, and record the outcome.

Context

Assemble a scoped pack, inspect selected passages and sources, compare retrieval profiles, and copy the rendered Markdown.

Models and Usage

Inspect client readiness, retained exchanges and optional host-reported model/token receipts. Unknown counts remain unknown; costs are not invented.

Learning

Rate memories for a task, pause or remove retrieval feedback, and create a lesson from a recorded outcome. Record a paired evaluation, promote an eligible lesson, or roll back its retrieval influence.

Setup

Choose tool participation, chat sharing, context limits and coordination roles. Manage features and verified Project Kit skills.

See which tool reported the work

Actual event-driven indicator and tool details in the running test workspace

The tool activity panel uses local Codex/OpenAI, Claude, DeepSeek and OpenCode icons. Hover, focus or select a tool to inspect its project, recorded conversations, coordination role, latest observed action and optional model receipts. Separate conversations stay identifiable when one tool has several workers.

Model, provider, effort and token counts come from explicit host reports. Missing values say Not reported. Activity indicators respond to new recorded events, respect Pause motion and reduced-motion preferences, and do not animate old history as new work. The icon identifies the tool, not the model it may be running.

Reporting MCP connections counts initialized project connections with a current heartbeat. Connections renew every ten seconds and expire after thirty seconds without renewal. This reports the memory transport; a connected tool may be idle. It does not count native apps that have not connected to this project.

The panel captures use four scripted MCP clients and synthetic model receipts. They demonstrate the working interface and transport, not four native applications or model inference.

Activity and session guide · Icon sources and license

Start with ordinary words

Working Teach the brain screen with reviewed project notes

  1. Open Knowledge and type: “The cupboard is black. Keep its brass handles.”

  2. Click Add to memory. The note and its original wording are saved in this project.

  3. Open Context and ask: “What colour is the cupboard?” Inspect the returned note and its source. A connected agent can request the same context through MCP.

  4. For longer notes or edits before saving, choose Review first, then save the useful parts. Pending and skipped parts stay outside shared retrieval.

  5. Use Learning to mark a memory useful, irrelevant or incorrect for a task, then inspect the effect on the next retrieval.

Direct notes support up to 6,000 characters and 20 paragraphs. No PDF, JSON or special format is required. The brain stores reference knowledge; your agent handles reasoning and answers from the context it requests. Notes and conversation import guide

flowchart LR
  Note[Your plain-language note] --> Save[Add to project memory]
  Save --> Recall[Relevant context with sources]
  Recall --> Codex[Codex]
  Recall --> Claude[Claude Code]
  Recall --> Other[OpenCode / Harness / MCP host]
  Other --> Feedback[Task feedback and reviewed outcomes]
  Feedback --> Recall

Continue where another agent stopped

Running Sessions view with reported history and an immutable handoff

An agent records meaningful progress and saves a checkpoint: what is done, decisions, evidence and next steps. Another connected agent calls session_resume with that checkpoint's ID and digest. It receives the exact saved handoff in a new linked session; the original remains available. This transfers recorded work, not hidden model state or an application's native running process.

Original tool history preserves names and conversation IDs supplied by supported sources. Codex has an explicit read-only connection to its installed app-server's project index; Claude Code, OpenCode and DeepSeek Harness support selected native exports. Missing original names remain unavailable. A saved history page is a bounded snapshot, and an operator adds a checkpoint before handing it to another agent. Sessions and native formats

flowchart LR
  A[Agent A in this project] --> Report[Progress and evidence]
  Report --> Checkpoint[Immutable checkpoint]
  Checkpoint --> B[Agent B resumes shared work]
  Checkpoint --> Audit[Original history retained]
  Control[Your sharing controls] --> Checkpoint

Follow evidence from a PDF to a context pack

Working PDF intake with extracted text, a page locator, and approved project memory

flowchart LR
  PDF[Local PDF] --> Parse[Extract page text]
  Parse --> Review[Review cited page]
  Review -->|Approve| Memory[Project memory]
  Memory --> Pack[Scoped context pack]
  Pack --> Host[Copy or retrieve through MCP]

The project store records the document fingerprint and the approved page citation. An image-only page shows that OCR is needed. Context budget figures estimate rendered pack tokens, and profile comparisons use the same scoped request. Optional host-reported token receipts appear separately in Usage. Context estimates do not prove a billing reduction. Context guide

Coordinate work and record a lesson

flowchart LR
  Goal[Project room] --> Msg[Proposal or critique]
  Msg --> Claim[Task claim and lease]
  Claim --> Artifact[Versioned file and digest]
  Artifact --> Outcome[Recorded outcome]
  Outcome --> Candidate[Lesson candidate]
  Candidate --> Evaluate[Operator records evaluation]
  Evaluate --> Promote[Explicit promotion]
  Promote --> Rollback[Rollback archives retrieval influence]

Browser and compatible project-local MCP clients share the same room records. Task claims carry revisions and expire. A recipient acknowledgement references the specific message or artifact. Learning changes project memory and retrieval. The workspace does not run models, train them, or assign work to hosts by itself. Workspace guide · Workflow integration

Actual learning view with a recorded comparison and rolled-back lesson

Browse the original evidence tools

The classic workspace offers memory curation, typed relationships, retrieval feedback, and the full Context Lab. The detailed activity view adds filters and playback controls for the loaded journal.

Classic Context Lab with selected and excluded evidence

Memory review with recorded sources and typed links

Activity diagnostics showing a recorded tool timeline

Connect your agent

Generate a recipe from the same directory used to start the project workspace. The recipe identifies the project store and launches the local stdio service.

shadow-brain project config . --target codex
shadow-brain skills install . --target codex

Preview the skill installation before adding --apply. Merge the printed recipe in the selected host, reconnect, and confirm it can list and call a tool such as project_inspect or context_pack. A recorded exchange will appear when activity recording and display are enabled. Integration guide

Target

Recipe

Codex

shadow-brain project config . --target codex

Claude Code

shadow-brain project config . --target claude-code

OpenCode

shadow-brain project config . --target opencode

DeepSeek Harness

shadow-brain project config . --target deepseek-harness

Other compatible host

shadow-brain project config . --target portable

The Setup page distinguishes installed files, configuration recipes, observed calls and host-reported usage. Tools must connect and request context; installing a package cannot make every application use it automatically. The Codex history adapter completed a real 0.145.0 handshake and an empty-project indexed list. History paging and imports were verified against controlled process fixtures; no personal native history was read for release testing.

Actual Setup view with project sharing, context limits and feature controls

Keep the workspace under your control

Set context token and entry ceilings, turn features on or off, and choose which conversations can be delivered to connected agents. Explicit source links carry those exclusions into retrieval and inherited handoffs. Tool switches use the client label supplied by a cooperating host; they are not authenticated access control. Already delivered context cannot be withdrawn from another application.

Enable project file activity only when you want file-change metadata. The live stream sends bounded change notifications; it does not repeatedly reload the whole dashboard. File events identify paths and times, while agent attribution requires an actual report. Measured local performance and limits

The dashboard separates reported model tokens, estimated context reduction, and measured tool duration. It never converts a smaller context pack into a claimed billing or speed saving.

Documentation

MIT license. Changelog

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Serves committed .context/ project memory over MCP stdio, letting agents query a codebase's architecture, decisions, constraints, and import graph to find which files a task touches, what depends on them, which tests cover them, and why the code is shaped that way. It also lets agents record decisions and annotate modules so later sessions inherit that knowledge, across one project or several in workspace mode.
      127 npm
      5
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables any MCP stdio client to share one local, evidence-backed project memory store, letting agents record verified facts and task outcomes, retrieve a token-budgeted context packet, and review, approve, or invalidate entries before they become active. Also supports handoff capsules and evidence-freshness recovery so stale or disputed memory is surfaced rather than silently reused.
      51 npm
      3
      MIT