Data Structure Protocol (DSP)

Habilidade de memória de longo prazo baseada em grafo para agentes de codificação de IA (LLM) — contexto mais rápido, menos tokens, refatorações mais seguras

GitHub

Documentação

Data Structure Protocol (DSP)

[!WARNING] Obsoleto. Este repositório não é mais desenvolvido. A habilidade atual é dsp-codegen — geração de código poliglota orientada por especificação a partir do grafo DSP (o grafo funciona como IR de compilador, não apenas como memória). Instale-o com um comando no Claude Code / Cursor / Codex / Hermes / OpenClaw. A nova habilidade é compatível com esta: grafos .dsp/ e marcadores @dsp existentes continuam funcionando, embora nem todos os recursos da habilidade antiga sejam mantidos.

A camada de memória que falta para o desenvolvimento assistido por IA

O problema

Seu agente relê o mesmo código-fonte a cada sessão. O DSP resolve isso.

Toda vez que você inicia uma nova tarefa, seu agente de codificação de IA gasta os primeiros 5–15 minutos "se orientando" — escaneando arquivos, rastreando imports, descobrindo o que depende do quê. Em projetos grandes, isso se torna um imposto constante sobre tokens e atenção. O contexto é reconstruído do zero, todas as vezes.

O DSP é uma memória estrutural de longo prazo baseada em grafo, armazenada em .dsp/. Ele dá aos agentes um mapa persistente e versionável do seu código-fonte — entidades, dependências, APIs públicas e as razões por trás de cada conexão — para que possam continuar exatamente de onde pararam.

O DSP não é outro framework de fluxo de trabalho. É a camada de memória estrutural persistente que falta em todo fluxo de trabalho de codificação de IA.

Instalação

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/k-kolomeitsev/data-structure-protocol/main/install.sh | bash

Windows:

irm https://raw.githubusercontent.com/k-kolomeitsev/data-structure-protocol/main/install.ps1 | iex

Codex:

$skill-installer install https://github.com/k-kolomeitsev/data-structure-protocol/tree/main/skills/data-structure-protocol

$skill-installer é uma invocação de habilidade do Codex — digite-o dentro de uma sessão do Codex CLI, não no seu shell.

O que você obtém

O agente para de reaprender seu projeto a cada sessão — o contexto estrutural persiste entre tarefas, sessões e até membros da equipe
Descoberta de dependências em segundos, não minutos — a travessia do grafo substitui a varredura completa do repositório
Análise de impacto antes de refatorações — saiba o que quebra antes de tocar no código
Mudanças mais seguras em bases de código brownfield — acoplamentos ocultos se tornam arestas visíveis no grafo
Funciona com Claude Code, Cursor, Codex — sem lock-in — DSP é uma habilidade de agente, não uma plataforma
Nativo do Git e versionável — .dsp/ é texto simples, diffs limpos, revisões como código

Compensação honesta: inicializar o DSP em um projeto grande exige esforço real (tempo, tokens, disciplina). Ele se paga ao longo da vida do projeto por meio de menor uso de tokens por tarefa, descoberta mais rápida e comportamento mais previsível do agente.

Como funciona

┌──────────────────────┐
│      Codebase        │
│  (files + assets)    │
└──────────┬───────────┘
           │  create/update graph as you work
           ▼
┌──────────────────────┐
│   DSP Builder / CLI  │
│   (dsp-cli.py)       │
└──────────┬───────────┘
           │  writes
           ▼
┌──────────────────────┐
│        .dsp/         │
│ entity graph + whys  │
└──────────┬───────────┘
           │  reads/searches/traverses
           ▼
┌──────────────────────┐
│   LLM Orchestrator   │
│ (your agent + skill) │
└──────────────────────┘

Conforme você trabalha, o DSP constrói um grafo leve do seu código-fonte: módulos, funções, dependências e APIs públicas. Cada conexão carrega um why — a razão pela qual existe. Seu agente lê esse grafo em vez de reescanear o repositório, navega pela estrutura por meio da travessia do grafo e mantém o grafo atualizado conforme o código evolui.

O grafo vive em .dsp/ — arquivos de texto simples que fazem commit, diff e merge como qualquer outro artefato de código-fonte.

Início rápido

Opção A: Comece pelo boilerplate (mais rápido)

dsp-boilerplate é um starter fullstack pronto para produção — NestJS 11 + React 19 + Vite 7 em Docker Compose, com um grafo DSP totalmente inicializado, habilidades pré-configuradas para todos os agentes, regras do Cursor, hooks do git e CI.

git clone https://github.com/k-kolomeitsev/dsp-boilerplate.git my-project
cd my-project
docker-compose up -d

Tudo está conectado: grafo .dsp/ com duas raízes (backend + frontend), marcadores @dsp em todos os arquivos de código-fonte, habilidades DSP para Cursor, Claude Code e Codex. Você pode começar a codificar e o agente já conhece toda a estrutura do projeto.

Opção B: Adicionar DSP a qualquer projeto

1. Inicializar

python dsp-cli.py --root . init

2. Criar entidades

python dsp-cli.py --root . create-object "src/app.ts" "Main application entrypoint"
# → obj-a1b2c3d4

python dsp-cli.py --root . create-function "src/app.ts#start" "Starts the HTTP server" --owner obj-a1b2c3d4
# → func-7f3a9c12

python dsp-cli.py --root . add-import obj-a1b2c3d4 obj-deadbeef "HTTP routing"

3. Navegar

python dsp-cli.py --root . search "authentication"
python dsp-cli.py --root . find-by-source "src/auth/index.ts"
python dsp-cli.py --root . get-children obj-a1b2c3d4 --depth 2

4. Análise de impacto

python dsp-cli.py --root . get-parents obj-a1b2c3d4 --depth inf
python dsp-cli.py --root . get-recipients obj-a1b2c3d4

Antes de qualquer refatoração, execute get-parents ou get-recipients para ver tudo que depende da entidade que você está prestes a alterar.

Agentes suportados

O DSP é instalado como uma habilidade para o seu agente. Escolha seu agente e escopo.

Ainda não tem um agente de codificação? Instale um primeiro:

Agente	Instalação
Claude Code	`npm i -g @anthropic-ai/claude-code` — docs
Cursor	cursor.com/downloads — docs
Codex CLI	`npm i -g @openai/codex` — docs \| github

macOS / Linux

Agente	Instalação no Projeto	Instalação Global
Cursor	`curl -fsSL https://raw.githubusercontent.com/k-kolomeitsev/data-structure-protocol/main/install.sh \| bash -s -- cursor`	`curl -fsSL https://raw.githubusercontent.com/k-kolomeitsev/data-structure-protocol/main/install.sh \| bash -s -- --global cursor`
Claude Code	`curl -fsSL https://raw.githubusercontent.com/k-kolomeitsev/data-structure-protocol/main/install.sh \| bash -s -- claude`	`curl -fsSL https://raw.githubusercontent.com/k-kolomeitsev/data-structure-protocol/main/install.sh \| bash -s -- --global claude`
Codex	`curl -fsSL https://raw.githubusercontent.com/k-kolomeitsev/data-structure-protocol/main/install.sh \| bash -s -- codex`	`curl -fsSL https://raw.githubusercontent.com/k-kolomeitsev/data-structure-protocol/main/install.sh \| bash -s -- --global codex`

Windows

# Project-level (current directory)
irm https://raw.githubusercontent.com/k-kolomeitsev/data-structure-protocol/main/install.ps1 | iex

# With specific agent
powershell -ExecutionPolicy Bypass -File install.ps1 -Agent cursor
powershell -ExecutionPolicy Bypass -File install.ps1 -Agent claude
powershell -ExecutionPolicy Bypass -File install.ps1 -Agent codex

# Global (user-level)
powershell -ExecutionPolicy Bypass -File install.ps1 -Agent cursor -Global

Codex (alternativa)

$skill-installer install https://github.com/k-kolomeitsev/data-structure-protocol/tree/main/skills/data-structure-protocol

$skill-installer é uma invocação de habilidade do Codex — digite-o dentro de uma sessão do Codex CLI, não no seu shell.

Instalação no projeto coloca a habilidade no seu repositório (.cursor/skills/, .claude/skills/, .codex/skills/). Instalação global coloca no seu diretório pessoal para que fique disponível em todos os projetos.

DSP vs alternativas

Agentes modernos já sabem planejar, escrever testes, verificar e entregar. Eles não precisam de invólucros de processo. O que lhes falta é memória.

	DSP	GSD	Superpowers
Ideia central	Memória estrutural persistente	Invólucro de processo/confiança	Disciplina de engenharia (TDD)
O que resolve	O agente não tem memória do projeto entre sessões	O agente não segue um fluxo de trabalho estruturado	O agente pode pular testes/planejamento
O problema é real?	Sim — nenhum modelo tem memória de projeto embutida	Diminuindo — modelos modernos planejam e verificam nativamente	Diminuindo — modelos modernos conhecem TDD quando solicitados
Memória persistente	Grafo completo entre sessões	Nenhuma	Nenhuma
Análise de impacto	Embutida (travessia do grafo)	Não	Não
Brownfield	Primeira classe	Varredura única	Sem suporte explícito
Sobrecarga	Baixa	Média	Média

Agentes modernos são mais inteligentes que a maioria dos engenheiros de nível médio. Eles planejam, testam, verificam. Só não conseguem lembrar do seu projeto. DSP é a solução. Comparação detalhada com GSD | Comparação detalhada com Superpowers

Conceitos principais

Conceito	O que é
Entidade	Um nó no grafo. Ou um Objeto (módulo/arquivo/classe/config/dependência externa) ou uma Função (função/método/handler)
UID	Identificador estável (`obj-<8hex>`, `func-<8hex>`). Caminhos de arquivo são atributos, não identidade — entidades sobrevivem a renomeações e movimentações
imports	Arestas de saída — o que esta entidade usa, com um `why` para cada conexão
shared	API pública de um objeto — o que ele expõe aos consumidores
exports/	Índice reverso — quem importa esta entidade e por quê (arestas de entrada)
TOC	Sumário por raiz listando todas as entidades da zona daquela raiz; a associação segue os escopos da raiz automaticamente

Marcadores UID ancoram a identidade no código-fonte:

// @dsp func-7f3a9c12
export function calculateTotal(items: Item[]): number { /* ... */ }

# @dsp func-3c19ab8e
def process_payment(order):
    ...

Formato de armazenamento

.dsp/ é texto simples em um layout de diretório determinístico:

.dsp/
├── TOC                        # Table of contents (single root)
├── TOC-<rootUid>              # One TOC per root (multi-root projects)
├── obj-a1b2c3d4/              # Object entity
│   ├── description            # source, kind, purpose
│   ├── imports                # imported UIDs (one per line)
│   ├── shared                 # exported/shared UIDs (one per line)
│   └── exports/               # reverse index
│       ├── <importer_uid>     # why the whole object is imported
│       └── <shared_uid>/      # per shared entity
│           ├── description    # what is exported
│           └── <importer_uid> # why this shared is imported
├── func-7f3a9c12/             # Function entity
│   ├── description
│   ├── imports
│   └── exports/
│       └── <owner_uid>        # ownership link
└── .cache/                    # derived reverse-index cache, kept in sync by the CLI
    ├── built                  # sentinel
    └── rev/<imported_uid>     # importer UIDs (one per line)

Especificação completa: ARCHITECTURE.md

Hooks do Git e CI

O DSP vem com hooks que mantêm o grafo sincronizado com seu código:

Hook	O que faz	Requer LLM
pre-commit	Verifica arquivos em staged contra o grafo DSP — sinaliza novos arquivos sem entidades, arquivos deletados ainda referenciados, órfãos	Não
pre-push	Integridade completa do grafo — detecção de órfãos, detecção de ciclos, resumo de estatísticas	Não
Revisão assistida por agente	Análise semântica profunda de mudanças contra entidades DSP, impacto de dependências	Sim

Instale os hooks:

./hooks/install-hooks.sh          # macOS/Linux
.\hooks\install-hooks.ps1         # Windows

Veja hooks/ para configuração, scripts independentes e integração com GitHub Actions.

Pacotes de integração

Configurações prontas para cada agente suportado:

Agente	Local da habilidade
Cursor	`.cursor/skills/data-structure-protocol/`
Claude Code	`.claude/skills/data-structure-protocol/`
Codex	`.codex/skills/data-structure-protocol/`

Cada integração inclui as instruções da habilidade (SKILL.md), CLI (dsp-cli.py) e documentação de referência. Veja integrations/ para guias de configuração específicos por agente.

Documentação

Documento	Descrição
dsp-boilerplate	Boilerplate fullstack (NestJS + React + Docker Compose) com DSP pré-inicializado — a maneira mais rápida de começar
GETTING_STARTED.md	Guia passo a passo da instalação até a primeira análise de impacto
ARCHITECTURE.md	Especificação completa do protocolo — modelo de entidade, formato de armazenamento, operações
docs/comparisons/	Comparações detalhadas com GSD, Superpowers e outras ferramentas
docs/workflows/	Guias de fluxo de trabalho — bootstrap, adoção brownfield, uso em equipe
integrations/	Guias e configurações de integração específicos por agente

Contribuindo

Contribuições são bem-vindas. Áreas onde a ajuda é mais valiosa:

Especificação da arquitetura — melhorando ARCHITECTURE.md
CLI — mantendo dsp-cli.py alinhado com a especificação
Instruções da habilidade — refinando SKILL.md para clareza do agente
Novas integrações — adicionando suporte para mais agentes e editores
Documentação — exemplos, guias de fluxo de trabalho, comparações

Por favor, mantenha as mudanças mínimas, explícitas e consistentes com a filosofia de "contexto mínimo suficiente".

Licença

Apache License 2.0 — veja LICENSE.