Agent, Memory & Orchestration Tools

This section covers agent orchestration, feedback, cross-session memory persistence, multi-step tool chaining, and runtime diagnostics.

sdl.agent.orchestrate

Autonomous task execution engine that selects the optimal Iris Gate Ladder path and collects evidence. Given a task type and description, the orchestrator:

Plans a rung path (card → skeleton → hotPath → raw) based on the task type and budget
Executes each rung in sequence, collecting evidence at each step
Returns the full execution trace: actions taken, evidence collected, metrics, and a synthesized answer

Planner token estimates: card ~50, skeleton ~200, hotPath ~500, raw ~2,000. When over budget, the planner trims rungs from the end while keeping at least one.

Always provide budget and scope with focusSymbols or focusPaths. Avoid requireDiagnostics unless needed — it can force a raw code rung.

Parameters

repoId

string

required

Repository identifier.

taskType

'debug' | 'review' | 'implement' | 'explain'

required

Type of task. Determines which rung path the planner selects.

taskText

string

required

Task description or prompt.

budget

object

Budget constraints for the orchestration run.

Show properties

maxTokens

number

Maximum tokens to consume.

maxActions

number

Maximum number of actions to execute.

maxDurationMs

number

Maximum duration in milliseconds.

options

object

Task-specific options.

Show properties

focusSymbols

string[]

Symbol IDs to focus on.

focusPaths

string[]

File paths to focus on.

includeTests

boolean

Include test files in analysis.

requireDiagnostics

boolean

Include diagnostic info (may force a raw rung).

Response

taskId

string

Unique task identifier.

taskType

string

Task type executed.

success

boolean

Whether the task completed successfully.

summary

string

Human-readable execution summary.

answer

string

Synthesized answer based on collected evidence.

nextBestAction

string

Suggested follow-up action.

error

string

Error message if the task failed.

path

object

The selected rung path.

Show properties

rungs

string[]

Ordered list of rungs executed.

estimatedTokens

number

Estimated total token cost.

estimatedDurationMs

number

Estimated duration.

reasoning

string

Why this rung path was selected.

actionsTaken

array

Each action executed during the run.

Show properties

string

Action identifier.

type

string

Action type (e.g., "card", "skeleton").

status

string

Execution status.

input

object

Input parameters.

output

object

Output data.

error

string | null

Error if the action failed.

timestamp

string

ISO timestamp.

durationMs

number

Action duration.

evidence

array

Evidence collected by this action.

finalEvidence

array

Consolidated evidence from all actions. Each: {type, reference, summary, timestamp}.

metrics

object

Execution metrics: {totalDurationMs, totalTokens, totalActions, successfulActions, failedActions, cacheHits}.

Example

{
  "repoId": "my-repo",
  "taskType": "debug",
  "taskText": "find root cause of auth timeout",
  "budget": { "maxTokens": 4000, "maxActions": 12 },
  "options": { "includeTests": true, "focusPaths": ["src/auth/"] }
}

sdl.agent.feedback

Records which symbols were useful or missing during a task, enabling offline tuning of slice relevance. After completing a task with a slice, the agent reports which symbols were actually useful and which expected symbols were missing. This feedback is stored in the graph database and used to improve future slice quality through reinforcement-style tuning.

Parameters

repoId

string

required

Repository identifier.

versionId

string

required

Ledger version the feedback applies to.

sliceHandle

string

required

Slice handle that was used.

usefulSymbols

string[]

required

Symbol IDs that were useful during the task. Minimum 1.

missingSymbols

string[]

Symbol IDs that were expected but absent from the slice.

taskTags

string[]

Tags describing the task.

taskType

'debug' | 'review' | 'implement' | 'explain'

Type of task performed.

taskText

string

Task description for context.

Response

boolean

Whether the feedback was recorded.

feedbackId

string

Unique feedback record ID.

repoId

string

Repository identifier.

versionId

string

Version identifier.

symbolsRecorded

number

Total symbols in the feedback record.

Example

{
  "repoId": "my-repo",
  "versionId": "v1770600000000",
  "sliceHandle": "h_abc123",
  "usefulSymbols": ["<symbol-id-1>", "<symbol-id-2>"],
  "missingSymbols": ["<symbol-id-3>"],
  "taskType": "debug",
  "taskText": "traced auth timeout to token expiry logic"
}

sdl.agent.feedback.query

Queries stored feedback records and aggregated statistics for offline tuning pipelines. Retrieves feedback records with optional filtering by version and time range. Returns both raw feedback entries and aggregated statistics showing the most commonly useful and most commonly missing symbols.

Parameters

repoId

string

required

Repository identifier.

versionId

string

Filter by version.

limit

number

Maximum records to return. Range: 1–1,000.

since

string

ISO timestamp to filter feedback from.

Response

repoId

string

Repository identifier.

feedback

array

Each: {feedbackId, versionId, sliceHandle, usefulSymbols, missingSymbols, taskTags, taskType, taskText, createdAt}.

aggregatedStats

object

{totalFeedback, topUsefulSymbols: [{symbolId, count}], topMissingSymbols: [{symbolId, count}]}.

hasMore

boolean

Whether more records exist.

Examples

{ "repoId": "my-repo", "versionId": "v1770600000000", "limit": 50 }

Memory Tools

SDL-MCP provides a graph-backed memory system for persisting decisions, bugfix context, and task notes across sessions. Memories are stored both in the graph database (fast querying) and as checked-in markdown files (.sdl-memory/*.md) for version control and team sharing. Memories are automatically surfaced inside graph slices — when building 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.

sdl.memory.store

Stores or updates a development memory with optional symbol and file links. Content-addressed deduplication prevents duplicate memories — if the same repoId + type + title + content hash already exists, the existing memory is returned.

Parameters

repoId

string

required

Repository identifier.

type

'decision' | 'bugfix' | 'task_context'

required

Memory type.

title

string

required

Short, scannable title. Range: 1–120 characters.

content

string

required

Memory content. Include the why, not just the what. Range: 1–50,000 characters.

Response

{ "ok": true, "memoryId": "<id>", "created": true, "deduplicated": false }

Example

{
  "repoId": "my-repo",
  "type": "bugfix",
  "title": "Race condition in authenticate()",
  "content": "The authenticate() function was not awaiting the token refresh promise, causing intermittent failures under concurrent requests.",
  "symbolIds": ["<symbol-id>"],
  "tags": ["auth", "concurrency"],
  "confidence": 0.9
}

sdl.memory.query

Searches and filters memories by text, type, tags, or linked symbols.

Parameters

repoId

string

required

Repository identifier.

query

string

Full-text search query across title and content. Maximum 1,000 characters.

types

string[]

Filter by memory types: "decision", "bugfix", "task_context".

Response

{ "memories": [ ... ], "total": 12 }

Examples

{ "repoId": "my-repo", "query": "auth token", "limit": 10 }

sdl.memory.remove

Soft-deletes a memory from the graph. Optionally also removes the backing .sdl-memory/*.md file from disk.

Parameters

repoId

string

required

Repository identifier.

memoryId

string

required

Memory ID to remove.

deleteFile

boolean

Also delete the backing markdown file from disk.

Response

{ "ok": true, "memoryId": "<id>", "fileDeleted": true }

Example

{ "repoId": "my-repo", "memoryId": "<memory-id>", "deleteFile": true }

sdl.memory.surface

Auto-surfaces memories relevant to a set of symbols or task type. Memories are ranked by confidence × recencyFactor × overlapFactor.

Parameters

repoId

string

required

Repository identifier.

symbolIds

string[]

Symbols to find related memories for. Maximum 500.

taskType

string

Filter by memory type: "decision", "bugfix", or "task_context".

limit

number

Maximum memories to return. Range: 1–50.

Response

Each SurfacedMemory includes all memory fields plus:

score — the ranking value
matchedSymbols — which of the queried symbols matched this memory

Example

{
  "repoId": "my-repo",
  "symbolIds": ["<symbol-id-1>", "<symbol-id-2>"],
  "limit": 5
}

sdl.chain

Executes a chain of SDL-MCP operations in a single round-trip with budget tracking and cross-step result passing. Takes an array of steps, each calling an action from the API manual or an internal data transform. Results flow between steps via $N references (e.g., $0.symbols[0].symbolId). Includes budget tracking, context-ladder validation, cross-step ETag caching, and optional execution tracing. Internal transforms: dataPick (project fields), dataMap (project from arrays), dataFilter (filter by clauses), dataSort (sort by field), dataTemplate (render template strings).

Parameters

repoId

string

required

Repository scope for all steps.

steps

array

required

Chain steps. Minimum 1. Each step: {fn: string, args?: object}. The fn field is the action name (e.g., "symbolSearch"). The args object supports $N references to previous step results.

budget

object

Budget constraints for the entire chain.

onError

'continue' | 'stop'

Error handling mode. "stop" halts the chain on any step failure; "continue" proceeds to the next step.

trace

object

Enable execution tracing for debugging.

Response

Array of step results plus budget usage metrics.

sdl.action.search

Searches the SDL action catalog for matching actions. Use this as the first discovery step before calling sdl.manual, sdl.chain, or direct tool surfaces.

Parameters

query

string

required

Search query.

limit

number

Maximum results. Range: 1–25.

includeSchemas

boolean

Include parameter schema summaries.

includeExamples

boolean

Include usage examples.

Response

{ "actions": [ ... ], "tokenEstimate": 420 }

sdl.manual

Returns the SDL-MCP API manual — a compact reference listing all available functions, their parameters, and return types. Call once per session to learn the API before using sdl.chain.

Parameters

query

string

Filter the manual to matching actions.

actions

string[]

Specific actions to include.

format

'typescript' | 'markdown' | 'json'

Output format.

includeSchemas

boolean

Include full parameter schemas.

includeExamples

boolean

Include usage examples.

Response

{ "manual": "...", "tokenEstimate": 1240 }

sdl.info

Returns a unified runtime and environment report for SDL-MCP. Collects the same diagnostic view as the CLI sdl-mcp info command.

Parameters

None.

Response

version

string

SDL-MCP package version.

runtime

object

{node, platform, arch}.

config

object

{path, exists, loaded}.

logging

object

{path, consoleMirroring, fallbackUsed}.

ladybug

object

{available, activePath}.

native

object

{available, sourcePath, disabledByEnv, reason}.

warnings

string[]

Non-fatal environment warnings.

misconfigurations

string[]

Actionable setup problems.

sdl.usage.stats

Returns cumulative token usage statistics and savings metrics. Tracks how many tokens SDL-MCP has saved compared to raw file reads across all tool calls.

Parameters

repoId

string

Repository identifier. Omit for global stats.

scope

'session' | 'history' | 'both'

Stats scope. Default: "both".

persist

boolean

Whether to persist current session stats.

since

string

ISO timestamp to filter historical stats from.

limit

number

Maximum historical entries to return. Range: 1–100.

Response

Token usage counters, savings estimates, compression ratios, and per-tool breakdowns. Session-scoped and/or historical aggregations depending on scope.

Examples

{ "repoId": "my-repo", "scope": "session" }

CLI

MCP Tools

Configuration

​sdl.agent.orchestrate

​Parameters

​Response

​Example

​sdl.agent.feedback

​Parameters

​Response

​Example

​sdl.agent.feedback.query

​Parameters

​Response

​Examples

​Memory Tools

​sdl.memory.store

​Parameters

​Response

​Example

​sdl.memory.query

​Parameters

​Response

​Examples

​sdl.memory.remove

​Parameters

​Response

​Example

​sdl.memory.surface

​Parameters

​Response

​Example

​sdl.chain

​Parameters

​Response

​sdl.action.search

​Parameters

​Response

​sdl.manual

​Parameters

​Response

​sdl.info

​Parameters

​Response

​sdl.usage.stats

​Parameters

​Response

​Examples

Build docs developers (and LLMs) love

sdl.agent.orchestrate

Parameters

Response

Example

sdl.agent.feedback

Parameters

Response

Example

sdl.agent.feedback.query

Parameters

Response

Examples

Memory Tools

sdl.memory.store

Parameters

Response

Example

sdl.memory.query

Parameters

Response

Examples

sdl.memory.remove

Parameters

Response

Example

sdl.memory.surface

Parameters

Response

Example

sdl.chain

Parameters

Response

sdl.action.search

Parameters

Response

sdl.manual

Parameters

Response

sdl.info

Parameters

Response

sdl.usage.stats

Parameters

Response

Examples