{"id":45905054,"url":"https://github.com/k-kolomeitsev/data-structure-protocol","last_synced_at":"2026-04-22T10:00:44.696Z","repository":{"id":339592579,"uuid":"1162585972","full_name":"k-kolomeitsev/data-structure-protocol","owner":"k-kolomeitsev","description":"Graph-based long-term memory skill for AI (LLM) coding agents — faster context, fewer tokens, safer refactors","archived":false,"fork":false,"pushed_at":"2026-03-22T15:40:28.000Z","size":94,"stargazers_count":23,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-23T06:38:51.851Z","etag":null,"topics":["agent-skills","ai","calude","claude-code","code-generation","code-review","codex","codex-skills","cursor","cursor-ai","gpt","openai","prompt-engineering","skills","structured-data"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/k-kolomeitsev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-20T12:54:49.000Z","updated_at":"2026-03-22T15:40:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/k-kolomeitsev/data-structure-protocol","commit_stats":null,"previous_names":["k-kolomeitsev/data-structure-protocol"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/k-kolomeitsev/data-structure-protocol","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k-kolomeitsev%2Fdata-structure-protocol","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k-kolomeitsev%2Fdata-structure-protocol/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k-kolomeitsev%2Fdata-structure-protocol/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k-kolomeitsev%2Fdata-structure-protocol/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/k-kolomeitsev","download_url":"https://codeload.github.com/k-kolomeitsev/data-structure-protocol/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k-kolomeitsev%2Fdata-structure-protocol/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32130776,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-22T08:34:57.708Z","status":"ssl_error","status_checked_at":"2026-04-22T08:34:55.583Z","response_time":58,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","ai","calude","claude-code","code-generation","code-review","codex","codex-skills","cursor","cursor-ai","gpt","openai","prompt-engineering","skills","structured-data"],"created_at":"2026-02-28T02:00:32.543Z","updated_at":"2026-04-22T10:00:44.691Z","avatar_url":"https://github.com/k-kolomeitsev.png","language":"Python","funding_links":[],"categories":["Sponsors ❤️","Code \u0026 Developer Tools"],"sub_categories":["Community Skills"],"readme":"[![GitHub stars](https://img.shields.io/github/stars/k-kolomeitsev/data-structure-protocol?style=social)](https://github.com/k-kolomeitsev/data-structure-protocol)\n[![License](https://img.shields.io/github/license/k-kolomeitsev/data-structure-protocol)](LICENSE)\n[![Python](https://img.shields.io/badge/python-3.10+-blue)](https://python.org)\n[![Claude Code](https://img.shields.io/badge/Claude_Code-supported-green)]()\n[![Cursor](https://img.shields.io/badge/Cursor-supported-green)]()\n[![Codex](https://img.shields.io/badge/Codex-supported-green)]()\n\n# Data Structure Protocol (DSP)\n\n**The missing memory layer for AI-assisted development**\n\n---\n\n## The problem\n\nYour agent re-reads the same codebase every session. **DSP fixes that.**\n\nEvery time you start a new task, your AI coding agent spends the first 5–15 minutes \"getting oriented\" — scanning files, tracing imports, figuring out what depends on what. On large projects this becomes a constant tax on tokens and attention. Context is rebuilt from scratch, every single time.\n\nDSP is a graph-based long-term structural memory stored in `.dsp/`. It gives agents a persistent, versionable map of your codebase — entities, dependencies, public APIs, and the *reasons* behind every connection — so they can pick up exactly where they left off.\n\n\u003e **DSP is not another workflow framework.** It's the persistent structural memory layer that's missing from every AI coding workflow.\n\n---\n\n## Install\n\n**macOS / Linux:**\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/k-kolomeitsev/data-structure-protocol/main/install.sh | bash\n```\n\n**Windows:**\n\n```powershell\nirm https://raw.githubusercontent.com/k-kolomeitsev/data-structure-protocol/main/install.ps1 | iex\n```\n\n**Codex:**\n\n```\n$skill-installer install https://github.com/k-kolomeitsev/data-structure-protocol/tree/main/skills/data-structure-protocol\n```\n\n---\n\n## What you get\n\n- **Agent stops re-learning your project every session** — structural context persists across tasks, sessions, and even team members\n- **Dependency discovery in seconds, not minutes** — graph traversal replaces full-repo scanning\n- **Impact analysis before refactors** — know what breaks before you touch it\n- **Safer changes on brownfield codebases** — hidden couplings become visible edges in the graph\n- **Works with Claude Code, Cursor, Codex — no lock-in** — DSP is an agent skill, not a platform\n- **Git-native and versionable** — `.dsp/` is plain text, diffs cleanly, reviews like code\n\n\u003e **Honest trade-off:** bootstrapping DSP on a large project takes real effort (time, tokens, discipline). It pays back over the project lifetime through lower per-task token usage, faster discovery, and more predictable agent behavior.\n\n---\n\n## How it works\n\n```\n┌──────────────────────┐\n│      Codebase        │\n│  (files + assets)    │\n└──────────┬───────────┘\n           │  create/update graph as you work\n           ▼\n┌──────────────────────┐\n│   DSP Builder / CLI  │\n│   (dsp-cli.py)       │\n└──────────┬───────────┘\n           │  writes\n           ▼\n┌──────────────────────┐\n│        .dsp/         │\n│ entity graph + whys  │\n└──────────┬───────────┘\n           │  reads/searches/traverses\n           ▼\n┌──────────────────────┐\n│   LLM Orchestrator   │\n│ (your agent + skill) │\n└──────────────────────┘\n```\n\nAs you work, DSP builds a lightweight graph of your codebase: modules, functions, dependencies, and public APIs. Each connection carries a `why` — the reason it exists. Your agent reads this graph instead of re-scanning the repo, navigates structure through graph traversal, and keeps the graph updated as code evolves.\n\nThe graph lives in `.dsp/` — plain text files that commit, diff, and merge like any other source artifact.\n\n---\n\n## Quick start\n\n### Option A: Start from the boilerplate (fastest)\n\n[**dsp-boilerplate**](https://github.com/k-kolomeitsev/dsp-boilerplate) is a production-ready fullstack starter — **NestJS 11 + React 19 + Vite 7** in Docker Compose, with a **fully initialized DSP graph**, pre-configured skills for all agents, Cursor rules, git hooks, and CI.\n\n```bash\ngit clone https://github.com/k-kolomeitsev/dsp-boilerplate.git my-project\ncd my-project\ndocker-compose up -d\n```\n\nEverything is wired: `.dsp/` graph with two roots (backend + frontend), `@dsp` markers in all source files, DSP skills for Cursor, Claude Code, and Codex. You can start coding and the agent already knows the entire project structure.\n\n### Option B: Add DSP to any project\n\n#### 1. Initialize\n\n```bash\npython dsp-cli.py --root . init\n```\n\n#### 2. Create entities\n\n```bash\npython dsp-cli.py --root . create-object \"src/app.ts\" \"Main application entrypoint\"\n# → obj-a1b2c3d4\n\npython dsp-cli.py --root . create-function \"src/app.ts#start\" \"Starts the HTTP server\" --owner obj-a1b2c3d4\n# → func-7f3a9c12\n\npython dsp-cli.py --root . add-import obj-a1b2c3d4 obj-deadbeef \"HTTP routing\"\n```\n\n#### 3. Navigate\n\n```bash\npython dsp-cli.py --root . search \"authentication\"\npython dsp-cli.py --root . find-by-source \"src/auth/index.ts\"\npython dsp-cli.py --root . get-children obj-a1b2c3d4 --depth 2\n```\n\n#### 4. Impact analysis\n\n```bash\npython dsp-cli.py --root . get-parents obj-a1b2c3d4 --depth inf\npython dsp-cli.py --root . get-recipients obj-a1b2c3d4\n```\n\n\u003e Before any refactor, run `get-parents` or `get-recipients` to see everything that depends on the entity you're about to change.\n\n---\n\n## Supported agents\n\nDSP installs as a skill for your agent. Pick your agent and scope.\n\nDon't have a coding agent yet? Install one first:\n\n| Agent | Install |\n|---|---|\n| **Claude Code** | `npm i -g @anthropic-ai/claude-code` — [docs](https://docs.anthropic.com/en/docs/claude-code/setup) |\n| **Cursor** | [cursor.com/downloads](https://www.cursor.com/downloads) — [docs](https://docs.cursor.com) |\n| **Codex CLI** | `npm i -g @openai/codex` — [docs](https://developers.openai.com/codex/cli) \\| [github](https://github.com/openai/codex) |\n\n### macOS / Linux\n\n| Agent | Project Install | Global Install |\n|---|---|---|\n| **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` |\n| **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` |\n| **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` |\n\n### Windows\n\n```powershell\n# Project-level (current directory)\nirm https://raw.githubusercontent.com/k-kolomeitsev/data-structure-protocol/main/install.ps1 | iex\n\n# With specific agent\npowershell -ExecutionPolicy Bypass -File install.ps1 -Agent cursor\npowershell -ExecutionPolicy Bypass -File install.ps1 -Agent claude\npowershell -ExecutionPolicy Bypass -File install.ps1 -Agent codex\n\n# Global (user-level)\npowershell -ExecutionPolicy Bypass -File install.ps1 -Agent cursor -Global\n```\n\n### Codex (alternative)\n\n```\n$skill-installer install https://github.com/k-kolomeitsev/data-structure-protocol/tree/main/skills/data-structure-protocol\n```\n\n\u003e **Project install** puts the skill in your repo (`.cursor/skills/`, `.claude/skills/`, `.codex/skills/`).\n\u003e **Global install** puts it in your home directory so it's available across all projects.\n\n---\n\n## DSP vs alternatives\n\nModern agents already know how to plan, write tests, verify, and ship. They don't need process wrappers. What they lack is **memory**.\n\n| | **DSP** | **GSD** | **Superpowers** |\n|---|---|---|---|\n| **Core idea** | Persistent structural memory | Process/confidence wrapper | Engineering discipline (TDD) |\n| **What it solves** | Agent has no memory of project between sessions | Agent doesn't follow structured workflow | Agent might skip tests/planning |\n| **Is the problem real?** | Yes — no model has built-in project memory | Diminishing — modern models plan and verify natively | Diminishing — modern models know TDD when prompted |\n| **Persistent memory** | Full graph across sessions | None | None |\n| **Impact analysis** | Built-in (graph traversal) | No | No |\n| **Brownfield** | First-class | One-time scan | No explicit support |\n| **Overhead** | Low | Medium | Medium |\n\n\u003e Modern agents are smarter than most mid-level engineers. They plan, they test, they verify. They just can't remember your project. DSP is the fix. [Detailed comparison with GSD](./docs/comparisons/dsp-vs-gsd.md) | [Detailed comparison with Superpowers](./docs/comparisons/dsp-vs-superpowers.md)\n\n---\n\n## Core concepts\n\n| Concept | What it is |\n|---|---|\n| **Entity** | A node in the graph. Either an **Object** (module/file/class/config/external dep) or a **Function** (function/method/handler) |\n| **UID** | Stable identifier (`obj-\u003c8hex\u003e`, `func-\u003c8hex\u003e`). File paths are attributes, not identity — entities survive renames and moves |\n| **imports** | Outgoing edges — what this entity uses, with a `why` for each connection |\n| **shared** | Public API of an object — what it exposes to consumers |\n| **exports/** | Reverse index — who imports this entity and why (incoming edges) |\n| **TOC** | Per-entrypoint table of contents listing all reachable entities from a root |\n\nUID markers anchor identity in source code:\n\n```ts\n// @dsp func-7f3a9c12\nexport function calculateTotal(items: Item[]): number { /* ... */ }\n```\n\n```python\n# @dsp func-3c19ab8e\ndef process_payment(order):\n    ...\n```\n\n---\n\n## Storage format\n\n`.dsp/` is plain text in a deterministic directory layout:\n\n```\n.dsp/\n├── TOC                        # Table of contents (single root)\n├── TOC-\u003crootUid\u003e              # One TOC per root (multi-root projects)\n├── obj-a1b2c3d4/              # Object entity\n│   ├── description            # source, kind, purpose\n│   ├── imports                # imported UIDs (one per line)\n│   ├── shared                 # exported/shared UIDs (one per line)\n│   └── exports/               # reverse index\n│       ├── \u003cimporter_uid\u003e     # why the whole object is imported\n│       └── \u003cshared_uid\u003e/      # per shared entity\n│           ├── description    # what is exported\n│           └── \u003cimporter_uid\u003e # why this shared is imported\n└── func-7f3a9c12/             # Function entity\n    ├── description\n    ├── imports\n    └── exports/\n        └── \u003cowner_uid\u003e        # ownership link\n```\n\nFull specification: [`ARCHITECTURE.md`](./ARCHITECTURE.md)\n\n---\n\n## Git hooks \u0026 CI\n\nDSP ships with hooks that keep the graph in sync with your code:\n\n| Hook | What it does | LLM required |\n|---|---|---|\n| **pre-commit** | Checks staged files against DSP graph — flags new files without entities, deleted files still referenced, orphans | No |\n| **pre-push** | Full graph integrity — orphan detection, cycle detection, stats summary | No |\n| **Agent-assisted review** | Deep semantic analysis of changes against DSP entities, dependency impact | Yes |\n\nInstall hooks:\n\n```bash\n./hooks/install-hooks.sh          # macOS/Linux\n.\\hooks\\install-hooks.ps1         # Windows\n```\n\nSee [`hooks/`](./hooks/) for configuration, standalone scripts, and GitHub Actions integration.\n\n---\n\n## Integration packs\n\nReady-made configurations for each supported agent:\n\n| Agent | Skill location |\n|---|---|\n| **Cursor** | `.cursor/skills/data-structure-protocol/` |\n| **Claude Code** | `.claude/skills/data-structure-protocol/` |\n| **Codex** | `.codex/skills/data-structure-protocol/` |\n\nEach integration includes the skill instructions (`SKILL.md`), CLI (`dsp-cli.py`), and reference docs. See [`integrations/`](./integrations/) for agent-specific setup guides.\n\n---\n\n## Documentation\n\n| Document | Description |\n|---|---|\n| [**dsp-boilerplate**](https://github.com/k-kolomeitsev/dsp-boilerplate) | Fullstack boilerplate (NestJS + React + Docker Compose) with DSP pre-initialized — the fastest way to start |\n| [**GETTING_STARTED.md**](./GETTING_STARTED.md) | Step-by-step guide from install to first impact analysis |\n| [**ARCHITECTURE.md**](./ARCHITECTURE.md) | Full protocol specification — entity model, storage format, operations |\n| [**docs/comparisons/**](./docs/comparisons/) | Detailed comparisons with GSD, Superpowers, and other tools |\n| [**docs/workflows/**](./docs/workflows/) | Workflow guides — bootstrap, brownfield adoption, team usage |\n| [**integrations/**](./integrations/) | Agent-specific integration guides and configurations |\n\n---\n\n## Contributing\n\nContributions are welcome. Areas where help is most valuable:\n\n- **Architecture spec** — improving [`ARCHITECTURE.md`](./ARCHITECTURE.md)\n- **CLI** — keeping `dsp-cli.py` aligned with the spec\n- **Skill instructions** — refining [`SKILL.md`](./skills/data-structure-protocol/SKILL.md) for agent clarity\n- **New integrations** — adding support for more agents and editors\n- **Documentation** — examples, workflow guides, comparisons\n\nPlease keep changes minimal, explicit, and consistent with the \"minimal sufficient context\" philosophy.\n\n---\n\n## License\n\nApache License 2.0 — see [`LICENSE`](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fk-kolomeitsev%2Fdata-structure-protocol","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fk-kolomeitsev%2Fdata-structure-protocol","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fk-kolomeitsev%2Fdata-structure-protocol/lists"}