Skip to main content

​
The Stale Context Problem

Traditional code indexing is a batch operation: index once, then the database is stale until you index again. For an AI agent helping you write code, this means the symbols it sees are always one step behind your edits. SDL-MCP’s live indexing system eliminates this gap. As you type in your editor, SDL-MCP receives buffer updates, parses them in the background, and overlays the new symbols on top of the durable database. Search, cards, and slices reflect your current code, not your last save.

​
Architecture

Editor (VSCode, etc.)
     │
     │  buffer events: open / change / save / close
     ▼
┌────────────────────┐
│  sdl.buffer.push   │  ← accepts full buffer content + metadata
└─────────┬──────────┘
          │
          ▼
┌────────────────────┐
│   Overlay Store    │  ← in-memory, draft-aware
│                    │
│  ┌──────────────┐  │
│  │ Dirty Buffers│  │  ← unsaved editor content
│  │ Parse Queue  │  │  ← background AST parsing
│  │ Symbol Cache │  │  ← extracted symbols from drafts
│  └──────────────┘  │
└─────────┬──────────┘
          │
   reads merge overlay     save / checkpoint
   with durable DB              │
          │                     ▼
          ▼              ┌──────────────┐
┌──────────────────┐     │  LadybugDB   │
│  MCP Tool Layer  │ ◄── │  (durable)   │
│  search / card / │     └──────────────┘
│  slice / skeleton│
└──────────────────┘
How it works:
  1. Buffer Push — Your editor extension sends the full file content on every keystroke (debounced) via sdl.buffer.push.
  2. Background Parse — The overlay store queues a tree-sitter parse to extract symbols from the draft content.
  3. Overlay Merge — When any tool queries the database (search, getCard, slice.build), the overlay symbols are merged on top of the durable DB results. Draft symbols shadow their durable counterparts.
  4. Checkpoint — On file save or manual checkpoint (sdl.buffer.checkpoint), the overlay is written to the durable LadybugDB graph.
  5. Reconciliation — A background reconciler ensures overlay and durable state converge, cleaning up stale drafts.

​
What Gets Overlaid

ToolOverlay Behavior
sdl.symbol.searchDraft symbols appear in results alongside durable symbols
sdl.symbol.getCardReturns draft symbol card if the file has unsaved changes
sdl.slice.buildIncludes draft symbols in the BFS traversal
sdl.code.getSkeletonGenerates skeleton from draft content
sdl.code.getHotPathSearches draft content for identifiers

​
VSCode Extension Setup

The sdl-mcp-vscode extension provides automatic buffer push integration so your editor changes flow into SDL-MCP without any manual intervention.
1

Install the extension

Install sdl-mcp-vscode from the VSCode marketplace or by loading it from the sdl-mcp-vscode/ directory in the SDL-MCP repository.
2

Enable live indexing in your config

Add the liveIndex block to your SDL-MCP configuration file:
{
  "liveIndex": {
    "enabled": true,
    "debounceMs": 75,
    "idleCheckpointMs": 15000,
    "maxDraftFiles": 200
  }
}
3

Open your repo in VSCode

Once the extension is active and the SDL-MCP server is running, the extension automatically sends sdl.buffer.push events for every file open, change, save, and close.
4

Verify live indexing is active

Check sdl.repo.status for the liveIndexStatus section:
{
  "liveIndexStatus": {
    "enabled": true,
    "pendingBuffers": 2,
    "dirtyBuffers": 1,
    "parseQueueDepth": 0,
    "checkpointPending": false,
    "lastCheckpointResult": "success"
  }
}

​
Buffer Tools

​
sdl.buffer.push

Manually push editor buffer content for live indexing. Accepts the full file content plus metadata about the buffer event type. The key flow: Editor keystrokes → sdl.buffer.push → Overlay Store → merged reads On save or idle, the overlay is flushed: 
Editor keystrokes → sdl.buffer.push → Overlay Store → merged reads
                                            │
                                       on save / idle
                                            │
                                            ▼
                                      LadybugDB (durable)

​
sdl.buffer.checkpoint

Force-write all pending overlay buffers to the durable LadybugDB. Use this when you want to ensure a snapshot is persisted — for example, before running a test suite or handing off work to another agent session.

​
sdl.buffer.status

Diagnostics for the live indexing pipeline. Returns queue depth, pending/dirty buffer counts, checkpoint status, and parse queue depth. Use this to investigate delays or verify the overlay store is healthy. 
{
  "enabled": true,
  "pendingBuffers": 0,
  "dirtyBuffers": 0,
  "parseQueueDepth": 0,
  "checkpointPending": false,
  "lastCheckpointResult": "success"
}

​
Configuration

{
  "liveIndex": {
    "enabled": true,           // master switch
    "debounceMs": 75,          // debounce between buffer events (25–5000, default: 75)
    "idleCheckpointMs": 15000, // auto-checkpoint after idle period (default: 15s)
    "maxDraftFiles": 200,      // max concurrent draft files (default: 200)
    "reconcileConcurrency": 1, // concurrent overlay→DB merge jobs (1–8)
    "clusterRefreshThreshold": 25 // reconciled symbols before cluster refresh
  }
}
OptionDefaultDescription
enabledtrueMaster switch for live indexing
debounceMs75Milliseconds to debounce between buffer push events
idleCheckpointMs15000Auto-checkpoint when the editor has been idle for this duration
maxDraftFiles200Maximum number of files that can be in the overlay simultaneously
reconcileConcurrency1Concurrent jobs merging overlay state into the durable DB
clusterRefreshThreshold25Number of reconciled symbols before triggering a cluster refresh

​
Performance Characteristics

  • Background AST parsing — tree-sitter parses happen on a separate queue and never block tool queries.
  • Debounced pushes — the 75ms default debounce prevents the overlay store from being flooded during rapid typing.
  • Overlay-first reads — all tool queries check the overlay before touching the durable DB, so draft symbols appear with no latency penalty.
  • Idle auto-checkpoint — after 15 seconds of editor inactivity, pending buffers are automatically flushed to LadybugDB.
For deeper diagnostics than sdl.repo.status provides, use sdl.buffer.status. It exposes the full queue state including per-file dirty status and parse queue depth.

Build docs developers (and LLMs) love

Get started for freeTalk to us