convez.ai
MCP ServerProdutividadeIntermediário
shipwright-ai

Shipwright Brain

shipwright-ai/shipwright-brain

Memória persistente baseada em arquivos Markdown para Claude Code

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP de memória persistente para Claude Code baseado em arquivos Markdown, sem banco de dados. Permite que Claude mantenha contexto de ideias, decisões e progresso entre sessões através de buscas semânticas e guias de formato auto-gerados.

Instalação

$npx convez-ai shipwright-ai/shipwright-brain

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
50%
Último commit
há 5 meses
Versão
v0.2.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Manter contexto de projetos entre múltiplas sessões de Claude Code
  • Organizar decisões, ideias e features com taxonomia dinâmica
  • Rastrear progresso de trabalho através de checklists que agregam automaticamente
  • Busca semântica em base de conhecimento sem infraestrutura de banco de dados

Veredito

Solução prática para estado persistente em Claude Code sem overhead de banco de dados. Abordagem baseada em Markdown com semântica embutida resolve um problema real: Claude esquece contexto entre sessões. Implementação sólida com UI integrada.

README

A tradução para o português deste README ainda está na fila.

Shipwright Brain

Persistent 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.

Part of the Shipwright a la carte toolkit.

Install

Plugin (recommended)

In Claude Code:

/plugin install shipwright-brain
/shipwright-brain:setup

Setup 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.

Via Shipwright

If you're using Shipwright, Brain is set up during Layer 2 of /shipwright:setup.

npx (no plugin)

cd your-project
npx github:shipwright-ai/shipwright-brain init

Creates docs/ and wires Brain into .mcp.json. Restart Claude Code for MCP to pick it up.

Manual

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "brain": {
      "command": "npx",
      "args": ["github:shipwright-ai/shipwright-brain", "mcp", "--dir", "./docs"]
    }
  }
}

Browse Your Memories

npx github:shipwright-ai/shipwright-brain ui

Starts Brain API on http://localhost:3111 and Shipwright UI on http://localhost:5173. The UI is downloaded automatically on first run (~2MB, cached in ~/.shipwright/brain-ui/).

Options:

npx github:shipwright-ai/shipwright-brain ui --port 4000          # Brain API on custom port
npx github:shipwright-ai/shipwright-brain ui --ui-port 8080       # UI on custom port
npx github:shipwright-ai/shipwright-brain api                     # API only, no UI

Init downloads everything upfront — Playwright Chromium (~150MB, for screenshots) and the embedding model (~80MB, for semantic search) — so there are no surprise delays during use.

What Makes Brain Different

Dynamic kinds and tags

No 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.

Format guides per kind

Each kind has its own template in docs/format-guides/{kind}/memory.md. Brain uses it when creating memories — Claude gets the right structure automatically.

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.

Sections — sibling .md files

Any .md file next to memory.md is a section. Brain parses them (frontmatter, checkboxes, progress).

Naming convention: {order}_{section}_{agent}.md

docs/ideas/auth-redesign/plan/task-1/
  memory.md                        <- the work-item
  1_execution_developer.md         <- developer checklist
  2_review_reviewer.md             <- reviewer checklist
  3_documentary_documenter.md      <- doc-writer checklist

Format guides can include section templates — they get copied automatically on create_memory.

Progress from checkboxes

No 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.

MCP responses steer Claude

This is the enforcement mechanism. Every Brain tool response includes:

  • NEXT STEPS — checklist of what Claude must do after creating a memory
  • CLAUDE_REMINDER — appended to every search/browse result ("update memories if scope changed")
  • Duplicate blocking — 90%+ similar memory blocks creation, presents two forced choices
  • Related memories — auto-linked as refs, suggested as parents

Claude follows these because they arrive fresh with every tool call — unlike CLAUDE.md rules that get compacted away.

Agent recall

Agents remember across sessions:

  • brain.recall_agent_memory({ agent_name: "developer" }) — returns learnings, auto-creates file if first time
  • brain.recall_developer_profile({}) — returns communication preferences, auto-detects user

Screenshots

Capture UI state at any breakpoint:

brain.screenshot({ url: "http://localhost:5173/profiles", memory_file: "docs/features/profiles/memory.md", width: 375 })

Width: 375 (mobile), 768 (tablet), omit for desktop (1280). Full page capture. Click sequences supported.

How It Works

Claude creates memories as markdown files with frontmatter. Brain handles everything else.

docs/
  ideas/
    auth-improvements/
      memory.md              <- the idea + checklist
      auth-plan/
        memory.md            <- plan (sub-memory)
        migrate-tokens/
          memory.md          <- work-item (sub-memory of plan)
          1_execution_developer.md  <- section
  decisions/
    jwt-tokens/
      memory.md
      whiteboard.png         <- attached files live next to the memory
  features/
    auth/
      memory.md              <- living feature doc
      login/
        memory.md            <- sub-feature

A memory looks like this:

---
title: Auth improvements
kind: ideas
tags: [auth, security, urgent]
refs: [docs/decisions/jwt-tokens/memory.md]
by: developer
at: 2025-03-28T10:00:00.000Z
---

> Why: session tokens don't meet compliance requirements
> What: switch to JWT with refresh tokens
> Who: all authenticated users
> How: implement token rotation, update API docs

- [x] Research refresh token best practices
- [x] Replace long-lived session tokens
- [ ] Add token rotation on refresh
- [ ] Update API docs

Brain reads the checkboxes and knows this is 2/4 = in progress.

MCP Tools

ToolWhat it does
create_memoryCreate memory with duplicate check, auto-refs, format guide, section templates
browse_memoriesNavigate tree by kind, filter by tags/status, sort, paginate
search_memoriesHybrid keyword + semantic search with filters
screenshotCapture URL at any viewport width with optional click sequence
attach_to_memoryAttach any file type to a memory
move_memoryMove memory to new parent, auto-update all refs
get_memory_graphFull connection graph
recall_agent_memoryLoad agent learnings from previous sessions
recall_developer_profileLoad developer preferences
delete_memoryRemove + cleanup refs

HTTP API

All endpoints return JSON with CORS headers.

EndpointParamsDescription
GET /api/browsepath, tags, status, sort, limit, offsetBrowse memory tree
GET /api/searchq, tags, kind, status, sort, limit, offsetHybrid search
GET /api/memoryf (memory_file)Full detail with rich refs/children
GET /api/graph--Full reference graph
GET /api/overview--Stats, kinds, tags
GET /filep (file path)Serve attachments

Related Projects

  • Shipwright — a la carte toolkit for Claude Code (methodology + orchestration)
  • Shipwright UI — web UI for browsing Brain memories

License

MIT

Ver o original no GitHub

Bom para

Relacionados