Brainwright
Provides a memory and validation layer for GitHub Spec Kit projects, reading Spec Kit artifacts such as specs, plans, tasks, checklists, and constitutions, and managing task status, decisions, and project memory.
Exports the project knowledge graph as an Obsidian vault so users can browse specs, tasks, decisions, notes, and their relationships in Obsidian.
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.
Brainwright
The memory and validation layer for GitHub Spec Kit projects.
Brainwright is an MCP server that lets a coding agent:
read only the Spec Kit artifact, or the section of it, that it needs;
check its work against the spec's requirements and acceptance scenarios;
mark tasks done exactly like
/speckit-implement;record decisions and remember what earlier sessions learned;
assemble the minimal context for a task;
ask a knowledge graph of the whole project how things relate, instead of reading files.
Everything stays plain Markdown in your repository, in Spec Kit's own layout. The graph can also be browsed as a Markdown report or an Obsidian vault.
Why
Spec Kit gives your agent a process: /speckit-specify → /speckit-plan → /speckit-tasks → /speckit-implement. Three problems remain during implementation:
Spec drift. As the session goes on, the agent drifts from
spec.mdand nobody notices until review.Amnesia between sessions. Decisions and pitfalls found while implementing are lost when the context ends.
Bloated context. To be safe, the agent rereads whole specs, plans and task lists.
Brainwright reads the files Spec Kit writes and gives the agent small, structured answers. It closes this loop:
spec.md → code → check_against_spec → set_task_status → log_decision / save_memoryRelated MCP server: Agent Harness Kit (AHK)
How it fits Spec Kit
Spec Kit writes | Brainwright |
| reads user stories, |
| returns any of them, or just one section |
| lists open |
| read-only, since checklist markers belong to the reviewer |
| returns it and makes its principles searchable |
(nothing) | adds |
Brainwright never creates features, plans or tasks. That stays with Spec Kit's skills.
Principles
Your files, Spec Kit's format. No proprietary layout. Everything is versioned in Git and readable by humans.
No LLM inside the server. It needs no API key and makes no model calls. The agent that calls it does the judging.
Well-described, non-overlapping tools. There are 18, and the whole
tools/liststays under 16,000 characters.No database. The cache never goes stale. The graph's cache is derived from your files, git-ignored and checked against each file's size and modification time on every call.
Safe by default.
The server has no network access and runs no commands.
It reads only
specs/,.specify/and the folders you list ingraph.include.It writes only
tasks.mdcheckboxes,.specify/memory/,.specify/graph/and the Obsidian vault folder.Writes are atomic and byte-minimal, and nothing is ever overwritten.
Tools
Tool | Use it to… |
| find the feature your task belongs to (id, title, status, artifacts, task progress, open clarifications) |
| read |
| see open |
| mark a task |
| send your diff before saying "done"; get requirements, success criteria, scenarios, edge cases, open tasks and a per-file summary |
| record a decision (Decision / Rationale / Alternatives considered) linked to a feature |
| list decisions by feature or date range |
| save a convention, learning or pitfall for future sessions |
| search notes, decisions and constitution principles, ignoring case and accents |
| get the most relevant spec and plan sections, open tasks, principles, decisions and cited files for a task, within a token budget; |
| ask a question and get a ranked subgraph of requirements, tasks, decisions and notes that fits a token budget |
| read one node ( |
| see the shortest chain of links between two nodes |
| get an overview: counts, most-connected nodes, communities, surprising connections and suggested questions |
| get the sections your agent has not analyzed yet, grouped into batches |
| store the relations and concepts your agent found, and mark sections as covered |
| find broken links, dangling relations, invalid ledger rows, orphans, duplicates and contradictions |
| write |
Full contracts: specs/009-speckit-format/contracts/tools.md for the first 10 tools, and the "Tool contracts" section of specs/010-second-brain/plan.md for the graph tools.
Quick start
Requires Node.js 22.12 or later.
1. Install
Claude Code (recommended)
No clone, npm ci or build is needed: the repository ships a self-contained dist/index.js.
claude plugin marketplace add ThiagoNascBarros/brainwright
claude plugin install brainwright@brainwrightRestart your Claude Code session afterwards so the MCP server is loaded. The server uses the session's working directory as the project root, so start Claude Code in your Spec Kit project. Do not also register a manual brainwright entry (below), or the server is registered twice.
Other MCP clients, or a manual setup
Open your agent in the Spec Kit project where you want to use Brainwright and paste this prompt:
Install the Brainwright MCP server for this project.
1. Run `node --version`. If it is older than 22.12, stop and tell me.
2. Clone https://github.com/ThiagoNascBarros/brainwright.git into a folder outside this project. In that clone, run `npm ci` and then `npm run build`.
3. Register the server with your MCP client, using the absolute path to `dist/index.js` in that clone. In Claude Code, run this from the root of this project: `claude mcp add brainwright -- node <absolute path>/dist/index.js`. In any other client that supports stdio servers, add an entry with `command` set to `node` and that path as the only argument.
4. Tell me if I need to restart the client, then call `list_features` and show me the result.2. Project-level configuration (manual install, any client)
To commit the configuration instead of registering the server per user, add a .mcp.json at the project root. It replaces the plugin install above:
{
"mcpServers": {
"brainwright": {
"command": "node",
"args": ["/absolute/path/to/brainwright/dist/index.js"],
"env": { "BRAINWRIGHT_ROOT": "." }
}
}
}A relative BRAINWRIGHT_ROOT is resolved against the server's working directory, so . only works if your client starts servers from the project root. If it does not, use an absolute path, such as /absolute/path/to/your-project.
Any MCP client that supports stdio servers works the same way.
3. Your first feature
Specs are written by Spec Kit's skills. Brainwright reads them. In your agent:
/speckit-specify Build a photo organizer with albums grouped by date.
/speckit-plan Use FastAPI and SQLite.
/speckit-tasksThen paste this prompt:
Use Brainwright. Call `list_open_tasks` for the feature you just created, filtered to story US1, and implement those tasks test-first. Before finishing, call `check_against_spec` with your diff, report any requirement that is not met, and mark each verified task with `set_task_status`.To try it without Spec Kit, copy examples/starter/ into a project. It holds specs/001-auth-login/ and a constitution.
Recommended agent instructions
Add this to your project's CLAUDE.md (Claude Code) or AGENTS.md (Codex). The ## Brainwright part is the same text the server sends to agents on initialize:
## Brainwright
Brainwright keeps this project's specs, tasks, decisions and notes as a knowledge graph. Before reading whole files or searching for a spec or design question, call query_graph (get_node for one id, find_path for how two things relate) and read only what it points to. Start a task with pack_context and close it with check_against_spec, set_task_status and log_decision. To grow the graph, call extraction_batch for a plan of pending units, give each batch to one worker that calls extraction_batch with those units and then save_relations with the relations, concepts and covered hashes; parallel workers must take different batches. Run lint_memory after renaming or deleting files. Files under .specify/graph/ are derived; never edit them.
## Spec Kit + Brainwright
- Start a task with `pack_context` (with the feature id), or `get_artifact` for one section. Do not read whole spec files.
- Before saying a task is done, call `check_against_spec` with your diff and report any unmet requirement or out-of-scope change.
- After verifying a task, call `set_task_status`. Record non-obvious choices with `log_decision`.
- Save conventions and pitfalls with `save_memory`; check `search_memory` before changing an approach.Second brain
Brainwright turns specs/, .specify/memory/ and any graph.include folders into one knowledge graph. It needs no model and no Obsidian.
What is in the graph. Every feature, artifact, requirement (FR-###), success criterion (SC-###), user story, task, constitution principle, decision, note and included document becomes a node with a typed id, such as requirement:001-photo-albums/FR-002 or decision:0007. Edges come from what the files already say: a feature contains its items, a task implements its story, and mentions, links, wikilinks and cited paths connect the rest.
The semantic layer. Your own agent (Claude Code, Codex…) adds the relations the text implies but never states, such as "decision 0007 is the rationale for FR-011":
extraction_batchwith no units returns a plan of the sections not analyzed yet, grouped into batches.For each batch, a worker calls
extraction_batchwith those units, reads them, and callssave_relationswith the relations, concepts and covered hashes. Parallel workers must take different batches.The relations land in Markdown tables in
.specify/memory/relations/<scope>.md, which you review and commit like any other file. A section is sent again only when its content changes.
To retire a wrong relation, save it as REJECTED (score 0): it stays in the ledger and is never re-added.
Without Obsidian.
Agents:
query_graph,get_node,find_pathandgraph_reportanswer from the graph, andlint_memorychecks it.Terminal: the same JSON as the tools. Replace
/path/to/brainwrightwith your clone; a plugin install has no clone, so use the plugin'sdist/index.jsunder~/.claude/plugins/.node /path/to/brainwright/dist/index.js graph report node /path/to/brainwright/dist/index.js graph query "album sorting" node /path/to/brainwright/dist/index.js graph node FR-002 --feature 001-photo-albums node /path/to/brainwright/dist/index.js graph path note:sorting-pitfall decision:0001 node /path/to/brainwright/dist/index.js graph lint node /path/to/brainwright/dist/index.js graph export reportExit codes: 0 on success; 1 on error, or for
lintwhen an error is found; 2 on bad usage; 3 when a reference is ambiguous; 4 when no node matches.GitHub:
export_graphwithreportwrites.specify/graph/GRAPH_REPORT.md, whose Mermaid diagrams render on GitHub;jsonwrites.specify/graph/graph.jsonfor other tools.
With Obsidian. export_graph with obsidian writes one note per node, with wikilinks, plus one note per community, to graph.vaultDir (default .specify/graph/vault). Open that folder with "Open folder as vault".
The default path starts with a dot, so the folder picker may hide it. If it does, set
graph.vaultDirto a visible folder such asbrainand open that one.Brainwright never touches
.obsidian/and never overwrites a file it did not write. It removes only its own files that are no longer produced.
Codex. Add the server to ~/.codex/config.toml, and the agent instructions above to AGENTS.md:
[mcp_servers.brainwright]
command = "node"
args = ["/absolute/path/to/brainwright/dist/index.js"]Configuration
Setting | Where | Default |
Project root |
| the working directory |
Maximum response size |
|
|
Extra Markdown folders for the graph (read-only) |
|
|
Graph cache |
|
|
Obsidian vault folder |
|
|
{ "maxResponseChars": 20000, "graph": { "include": ["docs"], "cache": "disk", "vaultDir": "brain" } }<project>/
├── specs/
│ └── 001-photo-albums/ # spec.md, plan.md, tasks.md, research.md, data-model.md,
│ # quickstart.md, contracts/, checklists/ (written by Spec Kit)
└── .specify/
├── brainwright.json # optional
└── memory/
├── constitution.md # written by /speckit-constitution
├── decisions/ # NNNN-<slug>.md, written by log_decision
├── notes/ # <slug>.md, written by save_memory
└── relations/ # <scope>.md, written by save_relations
└── graph/ # derived and git-ignored: cache.json, graph.json, GRAPH_REPORT.md, vault/Don't edit the files under .specify/graph/ by hand. They are rebuilt from your files.
Feature folders are recognized by Spec Kit's naming: NNN-short-name, or YYYYMMDD-HHMMSS-short-name.
Migrating from v0.1.0
v0.2.0 replaces the .brainwright/ format with Spec Kit's.
Each
.brainwright/specs/<id>.mdbecomesspecs/NNN-<id>/spec.md, in Spec Kit's spec template. Acceptance criteriaAC-nbecome requirementsFR-00n, and progress moves to atasks.mdwith oneT###per item.Move
.brainwright/decisions/*to.specify/memory/decisions/, and rename thespec_id:frontmatter key tofeature:with the new id. OldContext/Consequencessections stay readable.Move
.brainwright/memory/*to.specify/memory/notes/.Replace
BRAINWRIGHT_DIRwithBRAINWRIGHT_ROOT(the project root), and.brainwright/config.jsonwith.specify/brainwright.json.Rename the tools in your agent instructions:
v0.1.0 | v0.2.0 |
|
|
|
|
|
|
|
|
|
|
This repository went through the same migration in PR SW-8.
Performance
Medians measured with the test suite on a laptop:
Scenario | Budget | Result |
| < 500 ms | ~170 ms |
| < 500 ms | ~165 ms |
| < 200 ms | < 1 ms |
| < 300 ms | ~185 ms |
| < 1 s | ~365 ms |
2,000 sequential calls over stdio | p95 < 50 ms | p95 ~36 ms |
Graph cold build, 500 features + 1,000 notes | < 1.5 s | ~1.1 s |
Warm | < 200 ms | ~120–140 ms |
First | < 600 ms | ~400 ms |
First / repeated | < 1.5 s / < 300 ms | ~1.3 s / ~240 ms |
Graph cold build, 2,000 features + 5,000 notes | < 6 s | ~3.9 s |
The load scenarios also cover:
500 concurrent calls and 200 concurrent writes;
two server processes on the same root;
1,000 task updates;
2,000 features with 5,000 notes;
two processes saving relations into the same ledger.
See docs/tdd/phase-4.md and docs/tdd/phase-5.md.
Documentation
Document | Content |
The project's principles (Spec Kit) | |
Product requirements; architecture, formats, tool contracts and errors | |
Phases and features | |
Brainwright's own Spec Kit features (it is built with itself) | |
Why things are the way they are | |
RED → GREEN evidence, requirement → test maps, and load results |
Development
npm run build # compile to dist/
npm run typecheck # tsc for src and tests
npm test # unit, integration and stdio contract tests
npm run test:load # performance and load suites (serial)One module per entity:
features/,constitution/,decisions/,memory/,context/andgraph/, pluscli/for thegraphsubcommand;each has its own types, repository, pure logic, and one file per tool;
all sit on top of
storage/, the only layer that touches the disk.
See TRD §3.
Contributing
Contributions are welcome. See CONTRIBUTING.md: every change starts as a Spec Kit feature and is built test-first. Please follow the Code of Conduct.
Security
Please report vulnerabilities privately. See SECURITY.md.
License
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
Project memory, documentation and controlled secret access for AI coding agents.
Project memory for coding agents: requirements, decisions, code graph and delivery telemetry.
Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.
Spec-driven delivery: plans, solutions, ADRs, UX docs, tasks, rules and skills for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceEnables AI assistants to research, plan, generate requirements and user stories, create starter projects, analyze codebases, curate context, manage tasks, and execute multi-step development workflows.42 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI coding providers to run structured multi-agent workflows by claiming tasks, logging actions, managing handoffs, and enforcing server-side health gates across explorer, consultant, builder, and reviewer roles. Specifications stay as Markdown on disk while tracked task state, acceptance evidence, and completion checks are owned by the server.29 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI coding providers to run structured multi-agent workflows, manage specs and tracked tasks, record handoffs, and enforce health-gated completion evidence.29 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to retrieve project briefings, reserve and track tasks, and record checkpoints, passages, messages, and durable context so another AI can resume work using local SQLite-backed project memory.10,386 npmMIT