{
  "markdown": "# Shipwright Brain\n\nPersistent memory for Claude Code. Markdown files, no database. Brain remembers ideas, decisions, features, and progress across sessions so Claude doesn't start from zero every time.\n\nPart of the [Shipwright](https://github.com/shipwright-ai/shipwright) a la carte toolkit.\n\n## Install\n\n### Plugin (recommended)\n\nIn Claude Code:\n```\n/plugin install shipwright-brain\n/shipwright-brain:setup\n```\n\nSetup asks for docs directory (default `./docs`) and port (default `3111`). That's it — Brain tools are available as `brain.create_memory`, `brain.browse_memories`, etc.\n\n### Via Shipwright\n\nIf you're using [Shipwright](https://github.com/shipwright-ai/shipwright), Brain is set up during Layer 2 of `/shipwright:setup`.\n\n### npx (no plugin)\n\n```bash\ncd your-project\nnpx github:shipwright-ai/shipwright-brain init\n```\n\nCreates `docs/` and wires Brain into `.mcp.json`. Restart Claude Code for MCP to pick it up.\n\n### Manual\n\nAdd to `.mcp.json` in your project root:\n\n```json\n{\n  \"mcpServers\": {\n    \"brain\": {\n      \"command\": \"npx\",\n      \"args\": [\"github:shipwright-ai/shipwright-brain\", \"mcp\", \"--dir\", \"./docs\"]\n    }\n  }\n}\n```\n\n## Browse Your Memories\n\n```bash\nnpx github:shipwright-ai/shipwright-brain ui\n```\n\nStarts Brain API on http://localhost:3111 and [Shipwright UI](https://github.com/shipwright-ai/shipwright-ui) on http://localhost:5173. The UI is downloaded automatically on first run (~2MB, cached in `~/.shipwright/brain-ui/`).\n\nOptions:\n\n```bash\nnpx github:shipwright-ai/shipwright-brain ui --port 4000          # Brain API on custom port\nnpx github:shipwright-ai/shipwright-brain ui --ui-port 8080       # UI on custom port\nnpx github:shipwright-ai/shipwright-brain api                     # API only, no UI\n```\n\nInit downloads everything upfront — Playwright Chromium (~150MB, for screenshots) and the embedding model (~80MB, for semantic search) — so there are no surprise delays during use.\n\n## What Makes Brain Different\n\n### Dynamic kinds and tags\n\nNo predefined taxonomy. Create any kind — ideas, decisions, features, bugs, epics, sessions — whatever fits your project. Tags are freeform: `area/auth`, `priority/high`, `persona/admin`. Organize however makes sense.\n\n### Format guides per kind\n\nEach kind has its own template in `docs/format-guides/{kind}/memory.md`. Brain uses it when creating memories — Claude gets the right structure automatically.\n\n**Tag-aware sub-templates:** `brain.create_memory({ kind: \"ideas\", tags: [\"plan\"] })` looks for `docs/format-guides/ideas/plan/memory.md` first. Different tags get different formats from the same kind.\n\n### Sections — sibling .md files\n\nAny `.md` file next to `memory.md` is a section. Brain parses them (frontmatter, checkboxes, progress).\n\nNaming convention: `{order}_{section}_{agent}.md`\n\n```\ndocs/ideas/auth-redesign/plan/task-1/\n  memory.md                        <- the work-item\n  1_execution_developer.md         <- developer checklist\n  2_review_reviewer.md             <- reviewer checklist\n  3_documentary_documenter.md      <- doc-writer checklist\n```\n\nFormat guides can include section templates — they get copied automatically on `create_memory`.\n\n### Progress from checkboxes\n\nNo status field. Brain counts `- [ ]` and `- [x]` and derives: not-started / in-progress / done. Section checkboxes aggregate into memory progress. Child memories roll up into parent progress.\n\n### MCP responses steer Claude\n\nThis is the enforcement mechanism. Every Brain tool response includes:\n- **NEXT STEPS** — checklist of what Claude must do after creating a memory\n- **CLAUDE_REMINDER** — appended to every search/browse result (\"update memories if scope changed\")\n- **Duplicate blocking** — 90%+ similar memory blocks creation, presents two forced choices\n- **Related memories** — auto-linked as refs, suggested as parents\n\nClaude follows these because they arrive fresh with every tool call — unlike CLAUDE.md rules that get compacted away.\n\n### Agent recall\n\nAgents remember across sessions:\n- `brain.recall_agent_memory({ agent_name: \"developer\" })` — returns learnings, auto-creates file if first time\n- `brain.recall_developer_profile({})` — returns communication preferences, auto-detects user\n\n### Screenshots\n\nCapture UI state at any breakpoint:\n```\nbrain.screenshot({ url: \"http://localhost:5173/profiles\", memory_file: \"docs/features/profiles/memory.md\", width: 375 })\n```\n\nWidth: 375 (mobile), 768 (tablet), omit for desktop (1280). Full page capture. Click sequences supported.\n\n## How It Works\n\nClaude creates memories as markdown files with frontmatter. Brain handles everything else.\n\n```\ndocs/\n  ideas/\n    auth-improvements/\n      memory.md              <- the idea + checklist\n      auth-plan/\n        memory.md            <- plan (sub-memory)\n        migrate-tokens/\n          memory.md          <- work-item (sub-memory of plan)\n          1_execution_developer.md  <- section\n  decisions/\n    jwt-tokens/\n      memory.md\n      whiteboard.png         <- attached files live next to the memory\n  features/\n    auth/\n      memory.md              <- living feature doc\n      login/\n        memory.md            <- sub-feature\n```\n\nA memory looks like this:\n\n```markdown\n---\ntitle: Auth improvements\nkind: ideas\ntags: [auth, security, urgent]\nrefs: [docs/decisions/jwt-tokens/memory.md]\nby: developer\nat: 2025-03-28T10:00:00.000Z\n---\n\n> Why: session tokens don't meet compliance requirements\n> What: switch to JWT with refresh tokens\n> Who: all authenticated users\n> How: implement token rotation, update API docs\n\n- [x] Research refresh token best practices\n- [x] Replace long-lived session tokens\n- [ ] Add token rotation on refresh\n- [ ] Update API docs\n```\n\nBrain reads the checkboxes and knows this is 2/4 = in progress.\n\n## MCP Tools\n\n| Tool | What it does |\n|------|-------------|\n| `create_memory` | Create memory with duplicate check, auto-refs, format guide, section templates |\n| `browse_memories` | Navigate tree by kind, filter by tags/status, sort, paginate |\n| `search_memories` | Hybrid keyword + semantic search with filters |\n| `screenshot` | Capture URL at any viewport width with optional click sequence |\n| `attach_to_memory` | Attach any file type to a memory |\n| `move_memory` | Move memory to new parent, auto-update all refs |\n| `get_memory_graph` | Full connection graph |\n| `recall_agent_memory` | Load agent learnings from previous sessions |\n| `recall_developer_profile` | Load developer preferences |\n| `delete_memory` | Remove + cleanup refs |\n\n## HTTP API\n\nAll endpoints return JSON with CORS headers.\n\n| Endpoint | Params | Description |\n|----------|--------|-------------|\n| `GET /api/browse` | `path`, `tags`, `status`, `sort`, `limit`, `offset` | Browse memory tree |\n| `GET /api/search` | `q`, `tags`, `kind`, `status`, `sort`, `limit`, `offset` | Hybrid search |\n| `GET /api/memory` | `f` (memory_file) | Full detail with rich refs/children |\n| `GET /api/graph` | -- | Full reference graph |\n| `GET /api/overview` | -- | Stats, kinds, tags |\n| `GET /file` | `p` (file path) | Serve attachments |\n\n## Related Projects\n\n- [Shipwright](https://github.com/shipwright-ai/shipwright) — a la carte toolkit for Claude Code (methodology + orchestration)\n- [Shipwright UI](https://github.com/shipwright-ai/shipwright-ui) — web UI for browsing Brain memories\n\n## License\n\nMIT\n",
  "bytes": 7315,
  "sha": "6712df24869718de6f29ac51b2c965a318d2d70dc0f87f566ef96b2ad4569a02",
  "repo_slug": "shipwright-ai/shipwright-brain",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_shipwright_ai_shipwright_brain_shipwrigh_5b216de2/readme"
}