SYMBOL DELTA LEDGER

Cards-first code context for AI coding agents

Stop feeding entire files into the context window. Start giving agents exactly the code intelligence they need.

</div>

What's the problem?

Every time an AI coding agent reads a file to answer a question, it consumes thousands of tokens. Most of those tokens are irrelevant to the task. The agent doesn't need 500 lines of a file to know that validateToken takes a string and returns a Promise<User> — but it reads them anyway, because that's all it has.

Multiply that across a debugging session touching 20 files and you've burned 40,000+ tokens on context gathering alone.

SDL-MCP fixes this. It indexes your codebase into a searchable symbol graph and serves precisely the right amount of context through a controlled escalation path. An agent that uses SDL-MCP understands your code better while consuming a fraction of the tokens.

How it works — in 30 seconds

%%{init: {"theme":"base","themeVariables":{"background":"#ffffff","primaryColor":"#E7F8F2","primaryBorderColor":"#0F766E","primaryTextColor":"#102A43","secondaryColor":"#E8F1FF","secondaryBorderColor":"#2563EB","secondaryTextColor":"#102A43","tertiaryColor":"#FFF4D6","tertiaryBorderColor":"#B45309","tertiaryTextColor":"#102A43","lineColor":"#0F766E","textColor":"#102A43","fontFamily":"Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"},"flowchart":{"curve":"basis","htmlLabels":true}}}%%
flowchart TD
    Codebase["Your Codebase"]
    Indexer["Indexer<br/>12 languages<br/>Rust native or Tree-sitter fallback"]
    Graph["LadybugDB graph<br/>symbols, edges, metrics, versions"]
    MCP["Current MCP surfaces<br/>33 flat, 6 gateway, 4 Code Mode"]
    CLI["13 CLI commands"]
    HTTP["HTTP API and graph UI"]
    Agent["AI coding agent<br/>Claude Code, Claude Desktop, Cursor, Windsurf, Codex, Gemini"]

    Codebase e1@--> Indexer
    Indexer e2@--> Graph
    Graph e3@--> MCP
    Graph e4@--> CLI
    Graph e5@--> HTTP
    MCP e6@--> Agent

    classDef source fill:#E7F8F2,stroke:#0F766E,stroke-width:2px,color:#102A43;
    classDef process fill:#E8F1FF,stroke:#2563EB,stroke-width:2px,color:#102A43;
    classDef decision fill:#FFF4D6,stroke:#B45309,stroke-width:2px,color:#102A43;
    classDef storage fill:#F2E8FF,stroke:#7C3AED,stroke-width:2px,color:#102A43;
    classDef output fill:#FFE8EF,stroke:#BE123C,stroke-width:2px,color:#102A43;
    classDef muted fill:#F8FAFC,stroke:#64748B,stroke-width:1px,color:#102A43;
    classDef animate stroke:#0F766E,stroke-width:2px,stroke-dasharray:10\,5,stroke-dashoffset:900,animation:dash 22s linear infinite;
    class e1,e2,e3,e4,e5,e6 animate;

Index once — SDL-MCP parses every symbol in your repo and stores it as a compact metadata record (a "Symbol Card") in a graph database
Query efficiently — Agents use MCP tools to search, slice, and retrieve exactly the context they need
Escalate only when necessary — A four-rung ladder controls how much code the agent sees, from a 100-token card to full source (with justification required)

Prerequisites

Node.js 24+ is required (download). SDL-MCP uses Node.js features not available in earlier versions. Run node -v to check.

Peer dependency warnings during install? The tree-sitter grammar packages may produce ERESOLVE warnings about peer dependencies. These are harmless — the install succeeds and everything works correctly. Add --legacy-peer-deps to suppress them: npm install -g sdl-mcp --legacy-peer-deps. SDL-MCP's postinstall also verifies tree-sitter grammar bindings and rebuilds missing ones before pruning sources; installs that use --ignore-scripts should run npm rebuild tree-sitter tree-sitter-kotlin if a grammar is unavailable.

Quick Start

# Install (requires Node.js 24+)
npm install -g sdl-mcp

# Initialize, auto-detect languages, index your repo, and run health checks
sdl-mcp init -y --auto-index

# Start the MCP server for your coding agent
sdl-mcp serve --stdio

Point your MCP client at the server and the agent gains access to SDL-MCP's current configured surface. By default that is exclusive Code Mode; set codeMode.exclusive: false when you want Code Mode plus the regular flat or gateway tools in one session.

npx users: Replace sdl-mcp with npx --yes sdl-mcp@latest in all commands above.

Full Getting Started Guide →

The Iris Gate Ladder

The core innovation. Named after the adjustable aperture that controls light flow in optics, the Iris Gate Ladder lets agents dial their context "aperture" from a pinhole to wide-open.

%%{init: {"theme":"base","themeVariables":{"background":"#ffffff","primaryColor":"#E7F8F2","primaryBorderColor":"#0F766E","primaryTextColor":"#102A43","secondaryColor":"#E8F1FF","secondaryBorderColor":"#2563EB","secondaryTextColor":"#102A43","tertiaryColor":"#FFF4D6","tertiaryBorderColor":"#B45309","tertiaryTextColor":"#102A43","lineColor":"#0F766E","textColor":"#102A43","fontFamily":"Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"},"flowchart":{"curve":"basis","htmlLabels":true}}}%%
flowchart TB
    R1["~100 tokens<br/>Rung 1: Symbol Card<br/>Name, signature, summary, dependencies, metrics"]
    R2["~300 tokens<br/>Rung 2: Skeleton IR<br/>Signatures and control flow with bodies elided"]
    R3["~600 tokens<br/>Rung 3: Hot-Path Excerpt<br/>Identifier-focused lines with context"]
    R4["~2,000 tokens<br/>Rung 4: Raw Code Window<br/>Policy-gated full source"]

    R1 e1@--> R2
    R2 e2@--> R3
    R3 e3@--> R4

    classDef source fill:#E7F8F2,stroke:#0F766E,stroke-width:2px,color:#102A43;
    classDef process fill:#E8F1FF,stroke:#2563EB,stroke-width:2px,color:#102A43;
    classDef decision fill:#FFF4D6,stroke:#B45309,stroke-width:2px,color:#102A43;
    classDef storage fill:#F2E8FF,stroke:#7C3AED,stroke-width:2px,color:#102A43;
    classDef output fill:#FFE8EF,stroke:#BE123C,stroke-width:2px,color:#102A43;
    classDef muted fill:#F8FAFC,stroke:#64748B,stroke-width:1px,color:#102A43;
    classDef animate stroke:#0F766E,stroke-width:2px,stroke-dasharray:10\,5,stroke-dashoffset:900,animation:dash 22s linear infinite;
    class e1,e2,e3 animate;

Most questions are answered at Rungs 1-2 without ever reading raw code. That's where the token savings come from.

Scenario	Reading the file	Using the Ladder	Savings
"What does `parseConfig` accept?"	~2,000 tok	~100 tok	20x
"Show me the shape of `AuthService`"	~4,000 tok	~300 tok	13x
"Where is `this.cache` set?"	~2,000 tok	~500 tok	4x

Why it matters:

4–20x token savings on typical code understanding queries
Most questions answered at Rungs 1–2 without ever reading raw code
Controlled escalation prevents agents from over-consuming context
Policy-gated raw access ensures agents prove they need full source

Iris Gate Ladder Deep Dive →

Feature Tour

Symbol Cards — The Atoms of Understanding

Every function, class, interface, type, and variable becomes a Symbol Card: a compact metadata record (~100 tokens) containing everything an agent needs to understand a symbol without reading its code.

%%{init: {"theme":"base","themeVariables":{"background":"#ffffff","primaryColor":"#E7F8F2","primaryBorderColor":"#0F766E","primaryTextColor":"#102A43","secondaryColor":"#E8F1FF","secondaryBorderColor":"#2563EB","secondaryTextColor":"#102A43","tertiaryColor":"#FFF4D6","tertiaryBorderColor":"#B45309","tertiaryTextColor":"#102A43","lineColor":"#0F766E","textColor":"#102A43","fontFamily":"Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"},"flowchart":{"curve":"basis","htmlLabels":true}}}%%
flowchart TB
    Card["Symbol Card: validateToken"]
    Kind["Kind: function (exported)"]
    File["File: src/auth/jwt.ts:42-67"]
    Signature["Signature: (token: string, opts?: ValidateOpts) -> Promise<DecodedToken>"]
    Summary["Summary: validates JWT signature and expiration"]
    Invariants["Invariants: throws on expired token"]
    SideEffects["Side effects: logs to audit trail"]
    Deps["Dependencies: verifySignature, checkExpiry, jsonwebtoken, AuditLogger"]
    Metrics["Metrics: fan-in 12, fan-out 4, churn 3/30d"]
    Context["Context: auth-module, request-pipeline, auth.test.ts"]
    ETag["ETag: a7f3c2..."]

    Card e1@--> Kind
    Kind e2@--> File
    File e3@--> Signature
    Signature e4@--> Summary
    Summary e5@--> Invariants
    Invariants e6@--> SideEffects
    SideEffects e7@--> Deps
    Deps e8@--> Metrics
    Metrics e9@--> Context
    Context e10@--> ETag

    classDef source fill:#E7F8F2,stroke:#0F766E,stroke-width:2px,color:#102A43;
    classDef process fill:#E8F1FF,stroke:#2563EB,stroke-width:2px,color:#102A43;
    classDef decision fill:#FFF4D6,stroke:#B45309,stroke-width:2px,color:#102A43;
    classDef storage fill:#F2E8FF,stroke:#7C3AED,stroke-width:2px,color:#102A43;
    classDef output fill:#FFE8EF,stroke:#BE123C,stroke-width:2px,color:#102A43;
    classDef muted fill:#F8FAFC,stroke:#64748B,stroke-width:1px,color:#102A43;
    classDef animate stroke:#0F766E,stroke-width:2px,stroke-dasharray:10\,5,stroke-dashoffset:900,animation:dash 22s linear infinite;
    class e1,e2,e3,e4,e5,e6,e7,e8,e9,e10 animate;

Cards include confidence-scored call resolution (the pass-2 resolver traces imports, aliases, barrel re-exports, and tagged templates to produce accurate dependency edges), community detection (cluster membership), and call-chain tracing (process participation with entry/intermediate/exit roles).

Why it matters:

~100 tokens per symbol vs. ~2,000 tokens to read the full file
Confidence-scored dependency edges trace real call relationships across files
Community detection and call-chain tracing reveal architectural structure
ETag-based conditional requests avoid re-fetching unchanged symbols
Workflow ETag caching now seeds slice.build with knownCardEtags so repeated slice builds can skip unchanged cards

Indexing & Language Support Deep Dive →

Graph Slicing — The Right Context for Every Task

Instead of reading files in the same directory, SDL-MCP follows the dependency graph. Starting from symbols relevant to your task, it traverses weighted edges (call: 1.0, config: 0.8, import: 0.6), scores each symbol by relevance, and returns the N most important within a token budget.

%%{init: {"theme":"base","themeVariables":{"background":"#ffffff","primaryColor":"#E7F8F2","primaryBorderColor":"#0F766E","primaryTextColor":"#102A43","secondaryColor":"#E8F1FF","secondaryBorderColor":"#2563EB","secondaryTextColor":"#102A43","tertiaryColor":"#FFF4D6","tertiaryBorderColor":"#B45309","tertiaryTextColor":"#102A43","lineColor":"#0F766E","textColor":"#102A43","fontFamily":"Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"},"flowchart":{"curve":"basis","htmlLabels":true}}}%%
flowchart TD
    Task["Task: Fix the auth middleware"] e1@--> Slice["sdl.slice.build"]
    Slice e2@--> Auth["authenticate"]
    Slice e3@--> Validate["validateToken"]
    Slice e4@--> Config["JwtConfig"]
    Auth e5@--> Hash["hashPassword"]
    Validate e6@--> User["getUserById"]
    Config e7@--> Env["envLoader"]
    Env e8@-. frontier outside budget .-> Frontier["spillover frontier"]

    classDef source fill:#E7F8F2,stroke:#0F766E,stroke-width:2px,color:#102A43;
    classDef process fill:#E8F1FF,stroke:#2563EB,stroke-width:2px,color:#102A43;
    classDef decision fill:#FFF4D6,stroke:#B45309,stroke-width:2px,color:#102A43;
    classDef storage fill:#F2E8FF,stroke:#7C3AED,stroke-width:2px,color:#102A43;
    classDef output fill:#FFE8EF,stroke:#BE123C,stroke-width:2px,color:#102A43;
    classDef muted fill:#F8FAFC,stroke:#64748B,stroke-width:1px,color:#102A43;
    classDef animate stroke:#0F766E,stroke-width:2px,stroke-dasharray:10\,5,stroke-dashoffset:900,animation:dash 22s linear infinite;
    class e1,e2,e3,e4,e5,e6,e7,e8 animate;

Slices have handles, leases, refresh (delta-only updates), and spillover (paged overflow). You can also skip the symbol search entirely — pass a taskText string and SDL-MCP auto-discovers the relevant entry symbols.

Why it matters:

Follows the dependency graph, not directory boundaries, for cross-cutting context
Weighted edge scoring (call > config > import) prioritizes the most relevant symbols
Token-budgeted: returns only what fits within your budget (~800 tokens vs. ~16,000 for raw files)
Natural-language task-text auto-discovers entry symbols — no symbol IDs needed

Graph Slicing Deep Dive →

Delta Packs & Blast Radius — Semantic Change Intelligence

git diff tells you what lines changed. SDL-MCP tells you what that change means and who's affected.

%%{init: {"theme":"base","themeVariables":{"background":"#ffffff","primaryColor":"#E7F8F2","primaryBorderColor":"#0F766E","primaryTextColor":"#102A43","secondaryColor":"#E8F1FF","secondaryBorderColor":"#2563EB","secondaryTextColor":"#102A43","tertiaryColor":"#FFF4D6","tertiaryBorderColor":"#B45309","tertiaryTextColor":"#102A43","lineColor":"#0F766E","textColor":"#102A43","fontFamily":"Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"},"flowchart":{"curve":"basis","htmlLabels":true}}}%%
flowchart TD
    Change["Modified validateToken() signature"]
    Sig["signatureDiff<br/>added options?: object"]
    Inv["invariantDiff<br/>added throws on expired"]
    Fx["sideEffectDiff<br/>added logs to audit trail"]
    Blast["Blast radius"]
    A1["authenticate()<br/>distance 1"]
    A2["refreshSession()<br/>distance 1"]
    A3["AuthMiddleware<br/>distance 2"]
    A4["auth.test.ts<br/>re-run recommended"]

    Change e1@--> Sig
    Change e2@--> Inv
    Change e3@--> Fx
    Sig e4@--> Blast
    Inv e5@--> Blast
    Fx e6@--> Blast
    Blast e7@--> A1
    Blast e8@--> A2
    Blast e9@--> A3
    Blast e10@--> A4

    classDef source fill:#E7F8F2,stroke:#0F766E,stroke-width:2px,color:#102A43;
    classDef process fill:#E8F1FF,stroke:#2563EB,stroke-width:2px,color:#102A43;
    classDef decision fill:#FFF4D6,stroke:#B45309,stroke-width:2px,color:#102A43;
    classDef storage fill:#F2E8FF,stroke:#7C3AED,stroke-width:2px,color:#102A43;
    classDef output fill:#FFE8EF,stroke:#BE123C,stroke-width:2px,color:#102A43;
    classDef muted fill:#F8FAFC,stroke:#64748B,stroke-width:1px,color:#102A43;
    classDef animate stroke:#0F766E,stroke-width:2px,stroke-dasharray:10\,5,stroke-dashoffset:900,animation:dash 22s linear infinite;
    class e1,e2,e3,e4,e5,e6,e7,e8,e9,e10 animate;

PR risk analysis (sdl.pr.risk.analyze) wraps this into a scored assessment with findings, evidence, and test recommendations. Fan-in trend analysis detects "amplifier" symbols whose growing dependency count means changes ripple further over time.

Why it matters:

Semantic diffs show what a change means, not just what lines moved
Ranked blast radius identifies which dependent symbols are most at risk
Fan-in trend analysis detects "amplifier" symbols whose changes ripple further over time
PR risk scoring produces actionable findings with test re-run recommendations

Delta & Blast Radius Deep Dive →

Live Indexing — Real-Time Code Intelligence

SDL-MCP doesn't wait for you to save. As you type in your editor, buffer updates are pushed to an in-memory overlay store, parsed in the background, and merged with the durable database. Search, cards, and slices reflect your current code, not your last save.

%%{init: {"theme":"base","themeVariables":{"background":"#ffffff","primaryColor":"#E7F8F2","primaryBorderColor":"#0F766E","primaryTextColor":"#102A43","secondaryColor":"#E8F1FF","secondaryBorderColor":"#2563EB","secondaryTextColor":"#102A43","tertiaryColor":"#FFF4D6","tertiaryBorderColor":"#B45309","tertiaryTextColor":"#102A43","lineColor":"#0F766E","textColor":"#102A43","fontFamily":"Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"},"flowchart":{"curve":"basis","htmlLabels":true}}}%%
flowchart LR
    Editor["Editor keystrokes"] e1@--> Push["sdl.buffer.push"]
    Push e2@--> Overlay["Overlay store"]
    Overlay e3@--> Reads["Merged reads<br/>search, cards, slices"]
    Overlay e4@--> Persist["save / idle checkpoint"]
    Persist e5@--> DB["LadybugDB durable graph"]

    classDef source fill:#E7F8F2,stroke:#0F766E,stroke-width:2px,color:#102A43;
    classDef process fill:#E8F1FF,stroke:#2563EB,stroke-width:2px,color:#102A43;
    classDef decision fill:#FFF4D6,stroke:#B45309,stroke-width:2px,color:#102A43;
    classDef storage fill:#F2E8FF,stroke:#7C3AED,stroke-width:2px,color:#102A43;
    classDef output fill:#FFE8EF,stroke:#BE123C,stroke-width:2px,color:#102A43;
    classDef muted fill:#F8FAFC,stroke:#64748B,stroke-width:1px,color:#102A43;
    classDef animate stroke:#0F766E,stroke-width:2px,stroke-dasharray:10\,5,stroke-dashoffset:900,animation:dash 22s linear infinite;
    class e1,e2,e3,e4,e5 animate;

Why it matters:

Search, cards, and slices reflect unsaved editor changes in real time
No manual re-index needed during active development
Background AST parsing with in-memory overlay keeps queries fast

Live Indexing Deep Dive →

Governance & Policy — Controlled Access

Raw code access (Rung 4) is policy-gated. Agents must provide:

A reason explaining why they need raw code
Identifiers they expect to find in the code
An expected line count within configured limits

Requests that don't meet policy are denied with actionable guidance ("try getHotPath with these identifiers instead"). Every access is audit-logged.

The sandboxed runtime execution tool (sdl.runtime.execute) has its own governance layer: enabled by default, but still guarded by executable allowlisting, CWD jailing, environment scrubbing, concurrency limits, and timeout enforcement. The outputMode parameter ("minimal" | "summary" | "intent") defaults to "minimal" for ~95% token savings, with sdl.runtime.queryOutput enabling on-demand output retrieval when needed.

Why it matters:

Proof-of-need gating prevents agents from wastefully reading raw code
Denied requests include actionable next-best-action guidance
Full audit logging of every code access decision
Sandboxed runtime with executable allowlisting, CWD jailing, and environment scrubbing

Governance & Policy Deep Dive →

Agent Context — Task-Shaped Retrieval

sdl.context is SDL-MCP's task-shaped context engine. Give it a task type (debug, review, implement, explain), a description, and a budget — it selects the right Iris Gate rungs, collects evidence, and returns context tuned to the job. In Code Mode, sdl.context provides the same retrieval surface without dropping into sdl.workflow.

Unscoped natural-language context calls use confidence-gated hybrid retrieval by default. Exact symbol mentions and explicit focusPaths / focusSymbols stay on the fast path; low-confidence lexical results can escalate to bounded FTS + vector retrieval. Set options.semantic: true to force hybrid retrieval, or options.semantic: false to keep lexical-only behavior for deterministic debugging.

The feedback loop (sdl.agent.feedback) records which symbols were useful and which were missing, improving future slice quality.

For portable exports such as tickets and PR descriptions, use the CLI sdl-mcp summary command. It generates token-bounded context briefings in markdown, JSON, or clipboard format for use outside MCP environments.

Why it matters:

Task-shaped context retrieval plans the right Iris Gate path within a token budget
Confidence-gated hybrid retrieval improves discovery without slowing known-target lookups
Feedback loop records what was useful/missing, improving future slice quality
Portable context summaries export findings for use outside MCP environments

Agent Context Deep Dive → · Context Modes →

Sandboxed Runtime Execution

Run tests, linters, and scripts through SDL-MCP's governance layer instead of uncontrolled shell access. 16 runtimes (Node.js, Python, Go, Java, Rust, Shell, and more), code-mode or args-mode, smart output summarization with keyword-matched excerpts, and gzip artifact persistence.

Why it matters:

Run tests, linters, and scripts under governance instead of uncontrolled shell access
16 runtimes supported (Node, Python, Go, Java, Rust, Shell, and more)
Executable allowlisting, CWD jailing, timeout enforcement, and environment scrubbing
Smart output summarization with keyword-matched excerpts and gzip artifact persistence

Runtime Execution Deep Dive →

Development Memories — Cross-Session Knowledge Persistence (Opt-In)

Agents forget everything between sessions. SDL-MCP fixes this with an opt-in graph-backed memory system that lets agents store decisions, bugfix context, and task notes linked directly to the symbols and files they relate to. Memory is disabled by default and must be explicitly enabled in the configuration. When enabled, memories are stored both in the graph database (for fast querying) and as checked-in markdown files (for version control and team sharing).

%%{init: {"theme":"base","themeVariables":{"background":"#ffffff","primaryColor":"#E7F8F2","primaryBorderColor":"#0F766E","primaryTextColor":"#102A43","secondaryColor":"#E8F1FF","secondaryBorderColor":"#2563EB","secondaryTextColor":"#102A43","tertiaryColor":"#FFF4D6","tertiaryBorderColor":"#B45309","tertiaryTextColor":"#102A43","lineColor":"#0F766E","textColor":"#102A43","fontFamily":"Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"},"flowchart":{"curve":"basis","htmlLabels":true}}}%%
flowchart LR
    Session1["Agent session 1<br/>records bugfix memory"] e1@--> Store["sdl.memory.store"]
    Store e2@--> Graph["LadybugDB memory node"]
    Store e3@--> Files[".sdl-memory/bugfixes/<id>.md"]
    Graph e4@--> Link1["MEMORY_OF -> authenticate()"]
    Graph e5@--> Link2["HAS_MEMORY -> repo"]
    Session2["Agent session 2"] e6@--> Surface["sdl.memory.surface"]
    Surface e7@--> Graph
    Graph e8@--> Recall["Relevant memory surfaced<br/>race condition fix in authenticate()"]

    classDef source fill:#E7F8F2,stroke:#0F766E,stroke-width:2px,color:#102A43;
    classDef process fill:#E8F1FF,stroke:#2563EB,stroke-width:2px,color:#102A43;
    classDef decision fill:#FFF4D6,stroke:#B45309,stroke-width:2px,color:#102A43;
    classDef storage fill:#F2E8FF,stroke:#7C3AED,stroke-width:2px,color:#102A43;
    classDef output fill:#FFE8EF,stroke:#BE123C,stroke-width:2px,color:#102A43;
    classDef muted fill:#F8FAFC,stroke:#64748B,stroke-width:1px,color:#102A43;
    classDef animate stroke:#0F766E,stroke-width:2px,stroke-dasharray:10\,5,stroke-dashoffset:900,animation:dash 22s linear infinite;
    class e1,e2,e3,e4,e5,e6,e7,e8 animate;

When enabled, memories are automatically surfaced inside graph slices — when an agent builds a slice touching symbols with linked memories, those memories appear alongside the cards. During re-indexing, memories linked to changed symbols are flagged as stale, prompting agents to review and update them. Four MCP tools (store, query, remove, surface) provide full CRUD plus intelligent ranking by confidence, recency, and symbol overlap. Memory tools are only available when memory is enabled in the configuration.

Why it matters:

Structured knowledge persists across sessions, linked directly to symbols and files
Opt-in and disabled by default — enable via "memory": { "enabled": true } in config
When enabled, automatically surfaced inside graph slices when touching related symbols
Stale memories flagged when linked symbols change during re-indexing
Dual storage: graph DB for fast querying + markdown files for version control and team sharing

Development Memories Deep Dive →

SCIP Integration — Compiler-Grade Cross-References

Tree-sitter gives SDL-MCP fast, syntax-level symbol extraction across the supported TypeScript/JavaScript, Python, Go, Java, C#, C/C++, PHP, Rust, Kotlin, and Shell surface. SCIP (Source Code Intelligence Protocol) supplements this with compiler-grade cross-references from tools like scip-typescript, scip-go, and rust-analyzer. Generate a .scip index file, point SDL-MCP at it, and heuristic edges are upgraded to exact compiler-verified edges, external dependency symbols become first-class graph nodes, and new implements edges reveal interface/trait relationships that syntax analysis cannot discover.

%%{init: {"theme":"base","themeVariables":{"background":"#ffffff","primaryColor":"#E7F8F2","primaryBorderColor":"#0F766E","primaryTextColor":"#102A43","secondaryColor":"#E8F1FF","secondaryBorderColor":"#2563EB","secondaryTextColor":"#102A43","tertiaryColor":"#FFF4D6","tertiaryBorderColor":"#B45309","tertiaryTextColor":"#102A43","lineColor":"#0F766E","textColor":"#102A43","fontFamily":"Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"},"flowchart":{"curve":"basis","htmlLabels":true}}}%%
flowchart LR
    Compiler["Compiler / Type Checker"] e1@--> SCIP[".scip index file"]
    SCIP e2@--> Ingest["sdl.scip.ingest"]
    Ingest e3@--> Upgrade["Heuristic edges → exact edges"]
    Ingest e4@--> External["External dependency nodes"]
    Ingest e5@--> Implements["implements edges"]

    classDef source fill:#E7F8F2,stroke:#0F766E,stroke-width:2px,color:#102A43;
    classDef process fill:#E8F1FF,stroke:#2563EB,stroke-width:2px,color:#102A43;
    classDef decision fill:#FFF4D6,stroke:#B45309,stroke-width:2px,color:#102A43;
    classDef storage fill:#F2E8FF,stroke:#7C3AED,stroke-width:2px,color:#102A43;
    classDef output fill:#FFE8EF,stroke:#BE123C,stroke-width:2px,color:#102A43;
    classDef muted fill:#F8FAFC,stroke:#64748B,stroke-width:1px,color:#102A43;
    classDef animate stroke:#0F766E,stroke-width:2px,stroke-dasharray:10\,5,stroke-dashoffset:900,animation:dash 22s linear infinite;
    class e1,e2,e3,e4,e5 animate;

Why it matters:

Upgrades heuristic call resolution to compiler-verified exact edges (confidence 0.95)
External dependencies (npm packages, Go modules, crate deps) become searchable graph nodes
Interface/trait implementations tracked via implements edges
Auto-ingest on sdl.index.refresh keeps SCIP data current with zero manual steps
Complementary: tree-sitter provides structure, SCIP provides semantic precision

SCIP Integration Deep Dive →

CLI Tool Access — No MCP Server Required

Access SDL-MCP direct action aliases plus the low-risk action.search and manual metadata proxies from the command line with sdl-mcp tool. No MCP server, transport, or SDK is required.

# Search for symbols
sdl-mcp tool symbol.search --query "handleAuth" --output-format pretty

# Build a task-scoped slice
sdl-mcp tool slice.build --task-text "debug auth flow" --max-cards 50

# Pipe JSON args, chain commands
echo '{"repoId":"my-repo"}' | sdl-mcp tool symbol.search --query "auth"

# Apply a single-file targeted write
sdl-mcp tool file.write --repo-id my-repo --file-path config/app.json \
  --json-path server.port --json-value 8080

# Discover and inspect metadata without opening the graph DB
sdl-mcp tool action.search --query manual --summary-only
sdl-mcp tool manual --actions action.search --format json

Features include typed argument coercion (string, number, boolean, string[], json), budget flag merging, stdin JSON piping with CLI flag precedence, auto-resolved repoId from cwd for graph actions, four output formats (json, json-compact, pretty, table), typo suggestions, and per-action --help. Direct graph actions dispatch through the same gateway router and Zod schemas as the MCP server; action.search and manual run in process against the same metadata handlers used by MCP registration.

Why it matters:

36 direct graph/action aliases plus action.search and manual metadata proxies accessible from any terminal - no server, transport, or SDK required
Direct graph actions keep gateway-router/Zod parity; metadata proxies share the same MCP registration handlers
Four output formats (json, json-compact, pretty, table) for scripting and CI pipelines
Auto-resolves repoId from cwd, supports stdin JSON piping and per-action --help

CLI Tool Access Deep Dive →

Tool Gateway — Compact Tool Registration

The tool gateway projects the 35 gateway-routable SDL actions into 4 namespace-scoped tools (sdl.query, sdl.code, sdl.repo, sdl.agent), reducing tools/list overhead from the full flat schema surface to a compact gateway surface.

%%{init: {"theme":"base","themeVariables":{"background":"#ffffff","primaryColor":"#E7F8F2","primaryBorderColor":"#0F766E","primaryTextColor":"#102A43","secondaryColor":"#E8F1FF","secondaryBorderColor":"#2563EB","secondaryTextColor":"#102A43","tertiaryColor":"#FFF4D6","tertiaryBorderColor":"#B45309","tertiaryTextColor":"#102A43","lineColor":"#0F766E","textColor":"#102A43","fontFamily":"Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"},"flowchart":{"curve":"basis","htmlLabels":true}}}%%
flowchart LR
    Before["Flat mode<br/>38 tools<br/>2 universal + 36 flat"] e1@--> After["Gateway mode<br/>6 tools<br/>2 universal + 4 gateway"]
    After e2@--> Savings["Smaller tools/list payload<br/>lower agent startup overhead"]

    classDef source fill:#E7F8F2,stroke:#0F766E,stroke-width:2px,color:#102A43;
    classDef process fill:#E8F1FF,stroke:#2563EB,stroke-width:2px,color:#102A43;
    classDef decision fill:#FFF4D6,stroke:#B45309,stroke-width:2px,color:#102A43;
    classDef storage fill:#F2E8FF,stroke:#7C3AED,stroke-width:2px,color:#102A43;
    classDef output fill:#FFE8EF,stroke:#BE123C,stroke-width:2px,color:#102A43;
    classDef muted fill:#F8FAFC,stroke:#64748B,stroke-width:1px,color:#102A43;
    classDef animate stroke:#0F766E,stroke-width:2px,stroke-dasharray:10\,5,stroke-dashoffset:900,animation:dash 22s linear infinite;
    class e1,e2 animate;

Each gateway tool accepts an action discriminator field (e.g., { action: "symbol.search", repoId: "x", query: "auth" }) and routes to the same handlers with double Zod validation. Thin wire schemas in tools/list keep the registration compact while full validation happens server-side. The flat-only sdl.file.write action remains outside gateway mode today.

Why it matters:

Large reduction in tools/list overhead for gateway-first agents
35 gateway-routable actions consolidated into 4 namespace-scoped tools for simpler agent selection
Fewer tool choices means faster and more accurate tool dispatch by the agent
Choose Code Mode for task-shaped retrieval first; opt out of exclusive Code Mode when you also need regular flat or gateway tools

Tool Gateway Deep Dive →

Observability Dashboard

Built-in read-only dashboard surfaces every metric needed to diagnose SDL-MCP behaviour without parsing stderr logs. GlitterKill dark UI at /ui/observability on the HTTP transport or the loopback-only sdl-mcp serve --stdio --dashboard-port <port> sidecar, plus REST + SSE APIs (/api/observability/snapshot, /timeseries, /beam-explain, /stream) for programmatic access. Surfaces cache hit rates, hybrid-retrieval breakdowns (FTS / vector / PPR / RRF), beam-search decision traces, indexing pipeline metrics, write-pool and drain saturation, packed-wire token efficiency, and runtime CPU/memory/event-loop probes. See Observability Dashboard Deep Dive.

Current Tool Surface at a Glance

Mode	Tool count	Composition
Flat	`38`	`2` universal + `36` flat tools
Gateway	`6`	`2` universal + `4` gateway tools
Gateway + legacy	`42`	`2` universal + `4` gateway + `36` flat tools
Code Mode exclusive	`5`	`sdl.action.search`, `sdl.context`, `sdl.file`, `sdl.manual`, `sdl.workflow`

The generated source of truth is docs/generated/tool-inventory.md.

<table> <tr><th>Category</th><th>Tool</th><th>One-Line Description</th></tr> <tr><td rowspan="4">Repository</td> <td><code>sdl.repo.register</code></td><td>Register a codebase for indexing</td></tr> <tr><td><code>sdl.repo.status</code></td><td>Health, versions, watcher, prefetch, live-index stats</td></tr> <tr><td><code>sdl.repo.overview</code></td><td>Codebase summary: stats, directories, hotspots, clusters, with conditional ETag fetch support</td></tr> <tr><td><code>sdl.index.refresh</code></td><td>Trigger full or incremental re-indexing</td></tr> <tr><td rowspan="3">Live Buffer</td> <td><code>sdl.buffer.push</code></td><td>Push unsaved editor content for real-time indexing</td></tr> <tr><td><code>sdl.buffer.checkpoint</code></td><td>Force-write pending buffers to the durable database</td></tr> <tr><td><code>sdl.buffer.status</code></td><td>Live indexing diagnostics and queue depth</td></tr> <tr><td rowspan="3">Symbols</td> <td><code>sdl.symbol.search</code></td><td>Search symbols by name (with optional semantic reranking)</td></tr> <tr><td><code>sdl.symbol.getCard</code></td><td>Get one card or batch-fetch up to 100 cards with ETag-based conditional support</td></tr> <tr><td><code>sdl.symbol.edit</code></td><td>Preview/apply one symbol-scoped edit with AST, range, file, and draft preconditions</td></tr> <tr><td rowspan="3">Slices</td> <td><code>sdl.slice.build</code></td><td>Build a task-scoped dependency subgraph</td></tr> <tr><td><code>sdl.slice.refresh</code></td><td>Delta-only update of an existing slice</td></tr> <tr><td><code>sdl.slice.spillover.get</code></td><td>Page through overflow symbols beyond the budget</td></tr> <tr><td rowspan="3">Code Access</td> <td><code>sdl.code.getSkeleton</code></td><td>Signatures + control flow, bodies elided, with conditional ETag fetch support</td></tr> <tr><td><code>sdl.code.getHotPath</code></td><td>Lines matching specific identifiers + context, with conditional ETag fetch support</td></tr> <tr><td><code>sdl.code.needWindow</code></td><td>Full source code (policy-gated, requires justification)</td></tr> <tr><td>Deltas</td> <td><code>sdl.delta.get</code></td><td>Semantic diff + blast radius between versions</td></tr> <tr><td rowspan="2">Policy</td> <td><code>sdl.policy.get</code></td><td>Read current gating policy</td></tr> <tr><td><code>sdl.policy.set</code></td><td>Update line/token limits and identifier requirements</td></tr> <tr><td>Risk</td> <td><code>sdl.pr.risk.analyze</code></td><td>Scored PR risk with findings and test recommendations</td></tr> <tr><td rowspan="2">Agent</td> <td><code>sdl.agent.feedback</code></td><td>Record which symbols were useful or missing</td></tr> <tr><td><code>sdl.agent.feedback.query</code></td><td>Query aggregated feedback statistics</td></tr> <tr><td rowspan="2">Runtime</td> <td><code>sdl.runtime.execute</code></td><td>Sandboxed subprocess execution with outputMode (minimal/summary/intent)</td></tr> <tr><td><code>sdl.runtime.queryOutput</code></td><td>On-demand retrieval and keyword search of stored output artifacts</td></tr> <tr><td rowspan="4">Memory</td> <td><code>sdl.memory.store</code></td><td>Store or update a development memory with symbol/file links</td></tr> <tr><td><code>sdl.memory.query</code></td><td>Search memories by text, type, tags, or linked symbols</td></tr> <tr><td><code>sdl.memory.remove</code></td><td>Soft-delete a memory from graph and optionally from disk</td></tr> <tr><td><code>sdl.memory.surface</code></td><td>Auto-surface relevant memories for a task context</td></tr> <tr><td rowspan="3">Code Mode</td> <td><code>sdl.context</code></td><td>Code Mode task-shaped context retrieval for explain/debug/review/implement work</td></tr> <tr><td><code>sdl.workflow</code></td><td>Multi-step operations with budget tracking, ETag caching, and transforms</td></tr> <tr><td><code>sdl.manual</code></td><td>Self-documentation — query usage guide, action schemas, output format reference</td></tr> <tr><td>SCIP</td> <td><code>sdl.scip.ingest</code></td><td>Ingest a pre-built SCIP index for compiler-grade cross-references (with dry-run support)</td></tr> <tr><td rowspan="2">File</td> <td><code>sdl.file.read</code></td><td>Read non-indexed files (configs, docs, templates) with line-range, search, or JSON-path modes</td></tr> <tr><td><code>sdl.file.write</code></td><td>Policy-aware write helper for non-indexed files and templates</td></tr> <tr><td rowspan="3">Meta</td> <td><code>sdl.info</code></td><td>Runtime diagnostics — version, Node.js, platform, database, config paths</td></tr> <tr><td><code>sdl.usage.stats</code></td><td>Session and lifetime token savings statistics</td></tr> <tr><td><code>sdl.action.search</code></td><td>Search SDL action catalog to discover the right tool for a task</td></tr> </table>

Complete MCP Tools Reference (detailed parameters & responses) →

CLI Commands

Command	Description
`sdl-mcp init`	Bootstrap config, detect repo/languages, optionally auto-index
`sdl-mcp doctor`	Validate runtime, config, DB, grammars, repo access
`sdl-mcp index`	Index repositories (with optional `--watch` mode)
`sdl-mcp serve`	Start MCP server (`--stdio` or `--http`)
`sdl-mcp tool`	Access 36 direct action aliases (docs)
`sdl-mcp info`	Runtime diagnostics — version, Node.js, platform, database, config
`sdl-mcp summary`	Generate copy/paste context summaries from the CLI
`sdl-mcp health`	Compute composite health score with badge/JSON output
`sdl-mcp benchmark`	Run CI regression benchmarks
`sdl-mcp export`	Export sync artifact
`sdl-mcp import`	Import sync artifact
`sdl-mcp pull`	Pull by version/commit with fallback
`sdl-mcp version`	Show version and environment info

CLI Reference → · Configuration Reference →

Compatible With

SDL-MCP works with any MCP-compatible client:

Client	Transport	Setup
Claude Code	stdio	`sdl-mcp init --client claude-code`
Claude Desktop	stdio	`sdl-mcp init --client claude-code`
Cursor	stdio	Standard MCP server config
Windsurf	stdio	Standard MCP server config
Codex CLI	stdio	`sdl-mcp init --client codex`
Gemini CLI	stdio	`sdl-mcp init --client gemini`
OpenCode	stdio	`sdl-mcp init --client opencode`
Any MCP client	stdio / http	`sdl-mcp serve --stdio` or `--http`

A VSCode extension (sdl-mcp-vscode/) provides live buffer integration for real-time indexing of unsaved edits.

Tech Stack

Component	Technology
Runtime	Node.js 24+ / TypeScript 5.9+ (strict ESM)
Graph Database	LadybugDB (embedded, single-file)
Indexer (default)	Rust via napi-rs (multi-threaded)
Indexer (fallback)	tree-sitter + tree-sitter-typescript
MCP SDK	@modelcontextprotocol/sdk
Validation	Zod schemas for all payloads
Transports	stdio (agents) · HTTP (dev/network)

System Architecture

%%{init: {"theme":"base","themeVariables":{"background":"#ffffff","primaryColor":"#E7F8F2","primaryBorderColor":"#0F766E","primaryTextColor":"#102A43","secondaryColor":"#E8F1FF","secondaryBorderColor":"#2563EB","secondaryTextColor":"#102A43","tertiaryColor":"#FFF4D6","tertiaryBorderColor":"#B45309","tertiaryTextColor":"#102A43","lineColor":"#0F766E","textColor":"#102A43","fontFamily":"Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"},"flowchart":{"curve":"basis","htmlLabels":true}}}%%
flowchart TD
    Clients["MCP clients<br/>Claude Code, Claude Desktop, Cursor, Windsurf, Codex, Gemini"]
    Gateway["Tool gateway<br/>sdl.query, sdl.code, sdl.repo, sdl.agent"]
    Flat["Flat tools and optional code-mode surfaces"]
    Policy["Policy engine<br/>proof-of-need, budgets, audit logging"]
    Graph["LadybugDB graph<br/>symbols, edges, files, versions, memories"]
    Indexer["Indexer pipeline<br/>Rust native or Tree-sitter fallback<br/>pass 1, pass 2, semantic enrichment"]

    Clients e1@--> Gateway
    Clients e2@--> Flat
    Gateway e3@--> Policy
    Flat e4@--> Policy
    Policy e5@--> Graph
    Indexer e6@--> Graph

    classDef source fill:#E7F8F2,stroke:#0F766E,stroke-width:2px,color:#102A43;
    classDef process fill:#E8F1FF,stroke:#2563EB,stroke-width:2px,color:#102A43;
    classDef decision fill:#FFF4D6,stroke:#B45309,stroke-width:2px,color:#102A43;
    classDef storage fill:#F2E8FF,stroke:#7C3AED,stroke-width:2px,color:#102A43;
    classDef output fill:#FFE8EF,stroke:#BE123C,stroke-width:2px,color:#102A43;
    classDef muted fill:#F8FAFC,stroke:#64748B,stroke-width:1px,color:#102A43;
    classDef animate stroke:#0F766E,stroke-width:2px,stroke-dasharray:10\,5,stroke-dashoffset:900,animation:dash 22s linear infinite;
    class e1,e2,e3,e4,e5,e6 animate;

Full Architecture Documentation →

Documentation

Document	Description
Getting Started	Installation, 5-minute setup, MCP client config
MCP Tools Reference	Detailed docs for the current flat, gateway, and Code Mode surfaces
CLI Reference	All CLI commands and options
Configuration Reference	Every config option with defaults and guidance
Agent Workflows	Workflow instructions for CLAUDE.md / AGENTS.md
Architecture	Tech stack, data flow, component diagram
Iris Gate Ladder	Context escalation methodology
Troubleshooting	Common issues and fixes

Feature Deep Dives

Topic	What You'll Learn
Iris Gate Ladder	Four-rung context escalation with token savings analysis
Graph Slicing	BFS/beam search, edge weights, wire formats, auto-discovery
Delta & Blast Radius	Semantic diffs, ranked impact analysis, PR risk scoring
Live Indexing	Real-time editor buffer integration and overlay architecture
Governance & Policy	Proof-of-need gating, audit logging, runtime sandboxing
Agent Context	Task-shaped context retrieval, feedback loops, portable context summaries
Context Modes	Precise vs broad retrieval, adaptive symbol ranking, benchmark trade-offs
Indexing & Languages	Rust/TS engines, two-pass architecture, 12-language support
Runtime Execution	Sandboxed subprocess execution with governance
CLI Tool Access	Direct CLI access to 36 action aliases, output formats, stdin piping, scripting
Tool Gateway	35 gateway-routable actions, 4 namespace tools, thin schemas, migration guide
Semantic Engine	Pass-2 call resolution, embedding search, LLM summaries, confidence scoring
Semantic Embeddings Setup	Dependencies, model installation, provider configuration, tier-by-tier setup
Code Mode	`sdl.context`, `sdl.workflow`, action discovery, manual reference, one-call workflows
Development Memories	Graph-backed cross-session memory, file sync, staleness detection, auto-surfacing
SCIP Integration	Compiler-grade cross-references, external deps, implements edges, auto-ingest
Token Savings Meter	Per-call meter, session summaries, lifetime tracking, `sdl.usage.stats`

License

This project is source-available.

Free Use (Community License): You may use, run, and modify this software for any purpose, including internal business use, under the terms in LICENSE.
Commercial Distribution / Embedding: You must obtain a commercial license before you sell, license, sublicense, bundle, embed, or distribute this software as part of a for-sale or monetized product. See COMMERCIAL_LICENSE.md.

Questions? Contact gmullins.gkc@gmail.com.

GlitterKill/sdl mcp

What is GlitterKill/sdl mcp?

How to use GlitterKill/sdl mcp?

Key Features

Optimized Use Cases

GlitterKill/sdl mcp FAQ

Is GlitterKill/sdl mcp safe?

Is GlitterKill/sdl mcp up to date?

Are there any limits for GlitterKill/sdl mcp?

Official Documentation

SYMBOL DELTA LEDGER

Cards-first code context for AI coding agents

What's the problem?

How it works — in 30 seconds

Prerequisites

Quick Start

The Iris Gate Ladder

Feature Tour

Symbol Cards — The Atoms of Understanding

Graph Slicing — The Right Context for Every Task

Delta Packs & Blast Radius — Semantic Change Intelligence

Live Indexing — Real-Time Code Intelligence

Governance & Policy — Controlled Access

Agent Context — Task-Shaped Retrieval

Sandboxed Runtime Execution

Development Memories — Cross-Session Knowledge Persistence (Opt-In)

SCIP Integration — Compiler-Grade Cross-References

CLI Tool Access — No MCP Server Required

Tool Gateway — Compact Tool Registration

Observability Dashboard

Current Tool Surface at a Glance

CLI Commands

Compatible With

Tech Stack

System Architecture

Documentation

Feature Deep Dives

License

Global Ranking

Manual Config