DSP: Long-Term Code Structure Memory for AI Coding Agents
Persists your codebase's dependency graph in .dsp/ so AI agents stop re-scanning the repo every session — faster context, fewer tokens, safer refactors.
Runs fully locally: dsp-cli.py reads/writes only within .dsp/, no network calls or data exfiltration; UID regex validation doubles as path-safety; resolve-before-write reduces partial-write risk; read commands flagged read_only. Deducted for: remove-entity cascade deletion has no built-in confirmation or standalone rollback (relies on user's git); some destructive operations execute by default.
Docs and script are highly self-consistent: operations.md commands map one-to-one to the CLI, errors go to stderr with fix hints (e.g. missing --toc guidance), cache has a rebuild path. Static ceiling 10: no committed test suite or reproducible key-path execution evidence; the multi-subagent bootstrap flow is unverified.
Triggers are explicit (five scenarios: .dsp/ presence, DSP keywords, create/modify/delete code, etc.); fit and non-fit boundaries are mostly clear ('DSP is not human documentation'). Deducted for: no Chinese-language support noted; effectiveness depends on agent discipline with limited boundary description of environments/agent capabilities.
Well-layered docs (SKILL.md + three references), detailed operation semantics, storage format, FAQ-style import patterns, Apache-2.0 license. Heavy deduction: README explicitly declares the repository deprecated and unmaintained, pointing to dsp-codegen — maintenance ownership and update path are broken; no versioning or changelog seen.
Core task chain (structural memory, impact analysis, navigation) is complete with defined output contracts (e.g. UID as last stdout line); README honestly discloses bootstrap cost. Static ceiling 7: representative outputs unverified; token-savings claims vs. manual alternatives lack measured evidence.
Primary source code and detailed spec docs are auditable, but there are no tests, no CI evidence, no third-party execution or benchmarks; the core 'faster context, fewer tokens' claim cannot be independently corroborated.
- Repository is declared deprecated; maintenance moved to dsp-codegen — evaluate the successor instead of relying on this path
- remove-entity cascades without confirmation; operate on a clean git state for rollback
- .dsp/.cache/ can become inconsistent after merge/rebase; run rebuild-cache manually
- No tests or CI evidence; all reliability conclusions come from static reading, no execution
- No Chinese support; bootstrapping large projects is costly (tokens and time) — assess cost/benefit
What does this skill do, and when should you use it?
This skill gives AI coding agents a graph-based, long-term structural memory. It maintains an entity graph in a .dsp/ directory: modules, functions, and external dependencies each get a stable UID, with edges recording imports and the reason behind every connection. The agent reads and updates the graph via the dsp-cli.py script, replacing per-session full-repo scans with graph traversal. Note: the README explicitly marks this repository as deprecated; development has moved to dsp-codegen, which is compatible with existing .dsp/ graphs and @dsp markers.
Runs the Python script dsp-cli.py to read and write a plain-text entity graph in .dsp/: create-object/create-function build nodes, create-shared registers the public API, add-import records dependencies with a why, and remove-*/move-entity/update-description keep the graph in sync with code changes. Query commands include search, find-by-source, read-toc, get-children/get-parents, get-recipients (impact analysis), get-path, detect-cycles, get-orphans, and get-stats. Source files anchor identity with // @dsp <uid> comments. Ships with git pre-commit/pre-push hooks for graph integrity checks, and a three-wave parallel bootstrap algorithm for indexing existing codebases.
- Teams using AI agents on large brownfield codebases who want structural context (dependencies, public APIs) to persist across sessions instead of re-learning the repo each task.
- Developers planning a refactor: run get-parents or get-recipients to see everything that depends on an entity before touching it.
- Maintainers of multi-root projects (e.g., separate frontend and backend): each root gets its own TOC, and scopes auto-assign new entities.
- Teams wanting pre-commit detection of orphans and circular dependencies: install the bundled git hooks, which need no LLM.
- Situations where the agent must explain why a dependency exists: every import edge carries a why, indexed in the reverse exports/ directory.
What are this skill's strengths and limitations?
- Persists structural memory across sessions; the graph is plain text that commits, diffs, and reviews like code.
- UIDs are decoupled from file paths, so renames and moves never break graph identity.
- Built-in reverse-index cache keeps get-recipients/get-parents fast on large graphs without re-scanning.
- Ships with LLM-free git pre-commit/pre-push hooks for graph integrity checks.
- Works with Claude Code, Cursor, and Codex with no platform lock-in; a ready-made dsp-boilerplate gets you started fast.
- The README explicitly deprecates the project — development has stopped in favor of dsp-codegen (some old features not carried over).
- Bootstrapping a large codebase takes real effort in time, tokens, and team discipline.
- Graph upkeep depends on the agent strictly following the protocol; merge/rebase touching .dsp/ can corrupt the cache, requiring a manual rebuild-cache.
- Every code change requires extra CLI calls; internal-only changes can skip updates, but the workflow adds overhead overall.
- No test suite or third-party evaluation is presented in the source material.
How do you install this skill?
macOS/Linux: curl -fsSL https://raw.githubusercontent.com/k-kolomeitsev/data-structure-protocol/main/install.sh | bash (append cursor, claude, or codex to target an agent; --global for user-level). Windows: irm ...install.ps1 | iex (with -Agent and -Global flags). Inside a Codex session: $skill-installer install https://github.com/k-kolomeitsev/data-structure-protocol/tree/main/skills/data-structure-protocol. Project installs land in .cursor/skills/, .claude/skills/, or .codex/skills/. Git hooks: ./hooks/install-hooks.sh (Windows: install-hooks.ps1). Caveat: the README explicitly deprecates this repo in favor of the successor skill dsp-codegen.
How do you use this skill?
1) python dsp-cli.py --root . init to create .dsp/; 2) the agent follows the SKILL.md protocol: on new files run create-object + create-function --owner + create-shared, on new imports run add-import <importer> <imported> "why", and on deletions/moves/purpose changes call the matching remove-*/move-entity/update-description command; 3) navigate and query: search "authentication", find-by-source "src/auth/index.ts", get-children <uid> --depth 2, get-recipients <uid> for impact analysis; 4) bootstrap existing projects with the three-wave parallel algorithm (each file read exactly once); if .dsp/ was modified outside the CLI (merge/rebase, hand edits), run rebuild-cache. Trigger conditions: a .dsp/ directory exists, or the user mentions DSP, dsp-cli, or structure mapping.