Data Structure Protocol (DSP)

Habilidad de memoria a largo plazo basada en grafos para agentes de codificación de IA (LLM): contexto más rápido, menos tokens, refactorizaciones más seguras.

GitHub

Documentación

Data Structure Protocol (DSP)

[!WARNING] Obsoleto. Este repositorio ya no se desarrolla. La habilidad actual es dsp-codegen — generación de código políglota dirigida por especificación a partir del grafo DSP (el grafo funciona como IR de compilador, no solo como memoria). Instálalo con un solo comando en Claude Code / Cursor / Codex / Hermes / OpenClaw. La nueva habilidad es compatible con esta: los grafos .dsp/ existentes y los marcadores @dsp siguen funcionando, aunque no todas las funciones de la habilidad anterior se han trasladado.

La capa de memoria que falta para el desarrollo asistido por IA

El problema

Tu agente relee el mismo código base en cada sesión. DSP lo soluciona.

Cada vez que inicias una nueva tarea, tu agente de codificación con IA dedica los primeros 5–15 minutos a "orientarse" — escaneando archivos, rastreando imports, averiguando qué depende de qué. En proyectos grandes, esto se convierte en un impuesto constante sobre tokens y atención. El contexto se reconstruye desde cero, cada vez.

DSP es una memoria estructural de largo plazo basada en grafos almacenada en .dsp/. Proporciona a los agentes un mapa persistente y versionable de tu código base — entidades, dependencias, APIs públicas y las razones detrás de cada conexión — para que puedan retomar exactamente donde lo dejaron.

DSP no es otro framework de flujos de trabajo. Es la capa de memoria estructural persistente que falta en todo flujo de trabajo de codificación con IA.

Instalación

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 es una invocación de habilidad de Codex — escríbela dentro de una sesión de Codex CLI, no en tu terminal.

Lo que obtienes

El agente deja de reaprender tu proyecto en cada sesión — el contexto estructural persiste entre tareas, sesiones e incluso miembros del equipo
Descubrimiento de dependencias en segundos, no en minutos — el recorrido del grafo reemplaza el escaneo completo del repositorio
Análisis de impacto antes de refactorizar — sabe qué se rompe antes de tocarlo
Cambios más seguros en código base heredado — los acoplamientos ocultos se convierten en aristas visibles en el grafo
Funciona con Claude Code, Cursor, Codex — sin bloqueo de plataforma — DSP es una habilidad de agente, no una plataforma
Nativo de Git y versionable — .dsp/ es texto plano, se difiere limpiamente, se revisa como código

Compensación honesta: inicializar DSP en un proyecto grande requiere un esfuerzo real (tiempo, tokens, disciplina). Se amortiza durante la vida del proyecto mediante un menor uso de tokens por tarea, un descubrimiento más rápido y un comportamiento del agente más predecible.

Cómo 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) │
└──────────────────────┘

Mientras trabajas, DSP construye un grafo ligero de tu código base: módulos, funciones, dependencias y APIs públicas. Cada conexión lleva un why — la razón por la que existe. Tu agente lee este grafo en lugar de volver a escanear el repositorio, navega la estructura mediante el recorrido del grafo y mantiene el grafo actualizado a medida que el código evoluciona.

El grafo vive en .dsp/ — archivos de texto plano que se confirman, diferencian y fusionan como cualquier otro artefacto fuente.

Inicio rápido

Opción A: Comienza con la plantilla (la más rápida)

dsp-boilerplate es un iniciador fullstack listo para producción — NestJS 11 + React 19 + Vite 7 en Docker Compose, con un grafo DSP completamente inicializado, habilidades preconfiguradas para todos los agentes, reglas de Cursor, hooks de git y CI.

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

Todo está conectado: grafo .dsp/ con dos raíces (backend + frontend), marcadores @dsp en todos los archivos fuente, habilidades DSP para Cursor, Claude Code y Codex. Puedes empezar a codificar y el agente ya conoce toda la estructura del proyecto.

Opción B: Añade DSP a cualquier proyecto

1. Inicializar

python dsp-cli.py --root . init

2. Crear 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álisis de impacto

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

Antes de cualquier refactorización, ejecuta get-parents o get-recipients para ver todo lo que depende de la entidad que estás a punto de cambiar.

Agentes compatibles

DSP se instala como una habilidad para tu agente. Elige tu agente y su alcance.

¿Aún no tienes un agente de codificación? Instala uno primero:

Agente	Instalación
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	Instalación en proyecto	Instalación 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 es una invocación de habilidad de Codex — escríbela dentro de una sesión de Codex CLI, no en tu terminal.

Instalación en proyecto coloca la habilidad en tu repositorio (.cursor/skills/, .claude/skills/, .codex/skills/). Instalación global la coloca en tu directorio personal para que esté disponible en todos los proyectos.

DSP frente a alternativas

Los agentes modernos ya saben planificar, escribir pruebas, verificar y publicar. No necesitan envoltorios de proceso. Lo que les falta es memoria.

	DSP	GSD	Superpowers
Idea central	Memoria estructural persistente	Envoltorio de proceso/confianza	Disciplina de ingeniería (TDD)
Qué resuelve	El agente no tiene memoria del proyecto entre sesiones	El agente no sigue un flujo de trabajo estructurado	El agente podría omitir pruebas/planificación
¿El problema es real?	Sí — ningún modelo tiene memoria de proyecto integrada	Cada vez menor — los modelos modernos planifican y verifican de forma nativa	Cada vez menor — los modelos modernos conocen TDD cuando se les indica
Memoria persistente	Grafo completo entre sesiones	Ninguna	Ninguna
Análisis de impacto	Integrado (recorrido del grafo)	No	No
Código heredado	De primera clase	Escaneo único	Sin soporte explícito
Sobrecarga	Baja	Media	Media

Los agentes modernos son más inteligentes que la mayoría de los ingenieros de nivel medio. Planifican, prueban, verifican. Simplemente no pueden recordar tu proyecto. DSP es la solución. Comparación detallada con GSD | Comparación detallada con Superpowers

Conceptos centrales

Concepto	Qué es
Entidad	Un nodo en el grafo. Puede ser un Objeto (módulo/archivo/clase/config/dependencia externa) o una Función (función/método/handler)
UID	Identificador estable (`obj-<8hex>`, `func-<8hex>`). Las rutas de archivo son atributos, no identidad — las entidades sobreviven a renombrados y movimientos
imports	Aristas salientes — qué usa esta entidad, con un `why` para cada conexión
shared	API pública de un objeto — lo que expone a los consumidores
exports/	Índice inverso — quién importa esta entidad y por qué (aristas entrantes)
TOC	Tabla de contenidos por raíz que enumera todas las entidades de la zona de esa raíz; la pertenencia sigue automáticamente los alcances de la raíz

Los marcadores UID anclan la identidad en el código fuente:

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

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

Formato de almacenamiento

.dsp/ es texto plano en un diseño de directorios determinista:

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

Especificación completa: ARCHITECTURE.md

Hooks de Git y CI

DSP incluye hooks que mantienen el grafo sincronizado con tu código:

Hook	Qué hace	LLM requerido
pre-commit	Comprueba los archivos preparados contra el grafo DSP — señala archivos nuevos sin entidades, archivos eliminados aún referenciados, huérfanos	No
pre-push	Integridad completa del grafo — detección de huérfanos, detección de ciclos, resumen de estadísticas	No
Revisión asistida por agente	Análisis semántico profundo de los cambios contra las entidades DSP, impacto de dependencias	Sí

Instala los hooks:

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

Consulta hooks/ para configuración, scripts independientes e integración con GitHub Actions.

Paquetes de integración

Configuraciones listas para cada agente compatible:

Agente	Ubicación de la habilidad
Cursor	`.cursor/skills/data-structure-protocol/`
Claude Code	`.claude/skills/data-structure-protocol/`
Codex	`.codex/skills/data-structure-protocol/`

Cada integración incluye las instrucciones de la habilidad (SKILL.md), la CLI (dsp-cli.py) y la documentación de referencia. Consulta integrations/ para guías de configuración específicas por agente.

Documentación

Documento	Descripción
dsp-boilerplate	Plantilla fullstack (NestJS + React + Docker Compose) con DSP preinicializado — la forma más rápida de empezar
GETTING_STARTED.md	Guía paso a paso desde la instalación hasta el primer análisis de impacto
ARCHITECTURE.md	Especificación completa del protocolo — modelo de entidades, formato de almacenamiento, operaciones
docs/comparisons/	Comparaciones detalladas con GSD, Superpowers y otras herramientas
docs/workflows/	Guías de flujos de trabajo — inicialización, adopción en código heredado, uso en equipo
integrations/	Guías y configuraciones de integración específicas por agente

Contribuciones

Las contribuciones son bienvenidas. Las áreas donde más se valora la ayuda:

Especificación de arquitectura — mejorar ARCHITECTURE.md
CLI — mantener dsp-cli.py alineado con la especificación
Instrucciones de habilidad — refinar SKILL.md para mayor claridad del agente
Nuevas integraciones — añadir soporte para más agentes y editores
Documentación — ejemplos, guías de flujos de trabajo, comparaciones

Por favor, mantén los cambios mínimos, explícitos y coherentes con la filosofía de "contexto suficiente mínimo".

Licencia

Apache License 2.0 — consulta LICENSE.