Agent Shadow Brain
Integrates with Codex/OpenAI as a supported agent client, enabling project memory and context retrieval plus a read-only connection to Codex's app-server project index for session/history continuity.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.

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 62595For a reusable global command:
npm install -g @theihtisham/agent-shadow-brain@latest
shadow-brain --version
cd your-project
shadow-brain project workspace . --port 62595Keep 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

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

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

Open Knowledge and type: “The cupboard is black. Keep its brass handles.”
Click Add to memory. The note and its original wording are saved in this project.
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.
For longer notes or edits before saving, choose Review first, then save the useful parts. Pending and skipped parts stay outside shared retrieval.
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 --> RecallContinue where another agent stopped

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] --> CheckpointFollow evidence from a PDF to a context pack

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

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.



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 codexPreview 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 |
|
Claude Code |
|
OpenCode |
|
DeepSeek Harness |
|
Other compatible host |
|
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.

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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Hosted MCP server and Agent Skills for specs, engineering threads, and project memory.
Project management shared by people and AI agents, with persistent project state through MCP.
Private-by-default, local-first memory/context/task orchestrator for MCP apps and agents.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides a stdio MCP bridge for coding agents to query and record engineering knowledge locally, preserving debugging history, failed attempts, and verified solutions.MIT
- AlicenseNot gradedqualityBmaintenanceServes 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 npm5MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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 npm3MIT
- AlicenseNot gradedqualityCmaintenanceEnables agents and LLM hosts to connect over MCP stdio to versioned local memory, evidence recording, bounded WHAT IF scenario comparisons, and measured prediction scoring without granting real-world action execution.Apache 2.0