SDK Endpoint Contract

This page is the canonical contract for the SDK HTTP surface under /api/sdk/v1/*.

Use it when implementing direct HTTP integrations, debugging SDK client behavior, or validating backward compatibility in CI.

Transport clarification:

• SDK default transport is this HTTP surface (/api/sdk/v1/*).
• SDK can optionally use MCP JSON-RPC (/api/mcp) when you configure transport: "mcp" (or point baseUrl at /api/mcp).
• CLI commands are separate tooling and are not used by SDK runtime calls.

Base URL

https://memories.sh

Endpoint Matrix

Legacy aliases are still available:

• /api/mcp/key

Authentication

Runtime + graph endpoints

Send your API key:

Authorization: Bearer mem_xxx
Content-Type: application/json

Management endpoints

Use /api/sdk/v1/management/tenant-overrides for headless server-to-server tenant routing management.

Canonical Response Envelope

Every SDK v1 endpoint returns this envelope shape.

Success:

{
  "ok": true,
  "data": {},
  "error": null,
  "meta": {
    "version": "2026-02-11",
    "endpoint": "/api/sdk/v1/context/get",
    "requestId": "3a4f3fc2-24ea-4e9e-ac61-6f2807f39584",
    "timestamp": "2026-02-11T12:00:00.000Z"
  }
}

Failure:

{
  "ok": false,
  "data": null,
  "error": {
    "type": "validation_error",
    "code": "INVALID_REQUEST",
    "message": "Invalid request payload",
    "status": 400,
    "retryable": false,
    "details": {
      "field": "tenantId"
    }
  },
  "meta": {
    "version": "2026-02-11",
    "endpoint": "/api/sdk/v1/memories/add",
    "requestId": "8f2c34e5-2ed5-4a2f-92ea-c9d9faaf8db0",
    "timestamp": "2026-02-11T12:00:00.000Z"
  }
}

Error Semantics

Error types

• auth_error (401, 403)
• validation_error (400, 409)
• not_found_error (404)
• rate_limit_error (429)
• internal_error (500+)
• unknown_error (fallback classification)

Common error codes

Scope Model

Runtime + graph requests accept optional scoped routing under scope:

{
  "scope": {
    "tenantId": "acme-prod",
    "userId": "user_123",
    "projectId": "github.com/acme/platform"
  }
}

• tenantId: AI SDK Project selector (security/database boundary)
• userId: end-user scope inside tenantId
• projectId: optional repository context filter (not an auth boundary)

If tenantId is omitted, the request uses the API key owner's active workspace DB.

Request Constraints (Selected)

Runtime Endpoint Contracts

POST /api/sdk/v1/context/get

Retrieve context bundle (rules + memories + trace).

Request:

{
  "query": "deployment process",
  "limit": 5,
  "includeRules": true,
  "includeSkillFiles": true,
  "mode": "all",
  "strategy": "hybrid",
  "graphDepth": 1,
  "graphLimit": 8,
  "scope": {
    "tenantId": "acme-prod",
    "userId": "user_123",
    "projectId": "github.com/acme/platform"
  }
}

Defaults:

• limit: 5
• includeRules: true
• includeSkillFiles: true
• mode: all
• strategy: policy default (lexical until rollout policy promotes to hybrid)
• graphDepth: 1
• graphLimit: 8

Strategy aliases accepted for backward compatibility (deprecated):

• baseline → lexical
• hybrid_graph → hybrid

When aliases are used through @memories.sh/core, the client emits a one-time deprecation warning. Set MEMORIES_SUPPRESS_DEPRECATION_WARNINGS=true to silence those warnings in controlled environments.

Response data:

• mode, query
• rules[]
• memories[]
• conflicts[] (optional contradiction pairs when returned memories are linked by contradicts edges)
• skillFiles[]
• workingMemories[]
• longTermMemories[]
• trace (strategy, rollout mode, fallback details, candidate counts, retrieval policy diagnostics)

memories[].graph explainability (present for graph-expanded memories):

• whyIncluded: graph_expansion
• linkedViaNode: graph node label that connected the memory
• edgeType: relationship edge used for expansion
• hopCount: traversal depth from seed memory
• confidence: normalized edge confidence (0..1)
• seedMemoryId: originating seed memory id

conflicts[] item shape (ConflictPair in @memories.sh/core):

{
  "memoryAId": "mem_a",
  "memoryBId": "mem_b",
  "edgeType": "contradicts",
  "confidence": 0.91,
  "explanation": "These memories are linked by a contradiction edge from relationship extraction.",
  "suggestion": "These memories may conflict. Consider asking the user to clarify which preference is current."
}

trace includes rollout + retrieval diagnostics such as:

• retrievalPolicyDefaultStrategy, retrievalPolicyAppliedStrategy, retrievalPolicySelection
• semanticStrategyRequested, semanticStrategyApplied, semanticFallbackTriggered, semanticFallbackReason
• graphDepth, graphLimit, rolloutMode, shadowExecuted
• baselineCandidates, graphCandidates, graphExpandedCount, conflictCount, totalCandidates
• fallbackTriggered, fallbackReason

POST /api/sdk/v1/memories/add

Create a memory.

Request:

{
  "content": "Use canary rollout for graph retrieval changes",
  "type": "rule",
  "layer": "rule",
  "embeddingModel": "openai/text-embedding-3-small",
  "tags": ["rollout", "graph"],
  "paths": ["packages/web/src/app/**"],
  "category": "ops",
  "metadata": {
    "source": "runbook"
  },
  "scope": {
    "projectId": "github.com/acme/platform",
    "userId": "user_123"
  }
}

Success status is 201.

Response data:

• id
• message
• memory (structured memory record)
• embeddingModel
• embeddingModelSource

POST /api/sdk/v1/memories/search

Search memories by query.

Request:

{
  "query": "rollout",
  "type": "rule",
  "layer": "rule",
  "strategy": "hybrid",
  "limit": 10,
  "scope": {
    "userId": "user_123"
  }
}

Response data:

• memories[]
• count
• trace (requestedStrategy, appliedStrategy, fallback + candidate diagnostics)

POST /api/sdk/v1/memories/list

List recent memories with optional filters.

Request:

{
  "type": "rule",
  "layer": "rule",
  "tags": "rollout",
  "limit": 20,
  "scope": {
    "projectId": "github.com/acme/platform",
    "userId": "user_123"
  }
}

Response data:

• memories[]
• count

POST /api/sdk/v1/memories/edit

Update an existing memory.

Request:

{
  "id": "mem_abc123",
  "content": "Use canary then promote to full rollout after quality checks",
  "embeddingModel": "openai/text-embedding-3-small",
  "tags": ["rollout", "canary"],
  "scope": {
    "userId": "user_123"
  }
}

Requires at least one editable field beyond id (content, type, layer, tags, paths, category, or metadata).

Response data:

• id
• updated: true
• message
• embeddingModel
• embeddingModelSource

POST /api/sdk/v1/memories/forget

Soft-delete a memory.

Request:

{
  "id": "mem_abc123",
  "scope": {
    "userId": "user_123"
  }
}

Response data:

• id
• deleted: true
• message

POST /api/sdk/v1/memories/bulk-forget

Bulk soft-delete memories matching filters.

Request:

{
  "filters": {
    "types": ["note", "fact"],
    "tags": ["temporary"],
    "olderThanDays": 90,
    "pattern": "TODO*",
    "projectId": "github.com/acme/platform"
  },
  "dryRun": false,
  "scope": {
    "tenantId": "acme-prod",
    "userId": "user_123"
  }
}

Provide at least one filter (types, tags, olderThanDays, or pattern), or use all: true (cannot combine all with other filters).

Response data (dryRun: false):

• count
• ids[]
• message

Response data (dryRun: true):

• count
• memories[] (each with id, type, contentPreview)
• message

POST /api/sdk/v1/memories/vacuum

Permanently purge all soft-deleted memories to reclaim storage space.

Request:

{
  "scope": {
    "tenantId": "acme-prod",
    "userId": "user_123"
  }
}

Response data:

• purged
• message

POST /api/sdk/v1/memories/consolidate

Run consolidation to merge duplicates and supersede stale truths within scope.

Feature gate: MEMORY_CONSOLIDATION_ENABLED must be on (403 MEMORY_CONSOLIDATION_DISABLED when off).

Request:

{
  "types": ["rule", "decision", "fact"],
  "includeGlobal": true,
  "globalOnly": false,
  "dryRun": true,
  "model": "openai/gpt-5-mini",
  "scope": {
    "tenantId": "acme-prod",
    "userId": "user_123",
    "projectId": "github.com/acme/platform"
  }
}

Response data:

• runId
• message
• run (id, scope, projectId, userId, inputCount, mergedCount, supersededCount, conflictedCount, model, createdAt, metadata)
• winnerMemoryIds[]
• supersededMemoryIds[]

Typical endpoint-specific error codes:

• MEMORY_CONSOLIDATION_DISABLED (403)
• INVALID_REQUEST (400) for schema/shape violations

POST /api/sdk/v1/sessions/start

Start a lifecycle session.

Feature gate: MEMORY_SESSION_ENABLED must be on (403 MEMORY_SESSION_DISABLED when off).

Request:

{
  "title": "Auth migration rollout",
  "client": "codex",
  "metadata": {
    "channel": "oncall"
  },
  "scope": {
    "tenantId": "acme-prod",
    "userId": "user_123",
    "projectId": "github.com/acme/platform"
  }
}

Success status is 201.

Response data:

• sessionId
• message
• session (id, scope, projectId, userId, client, status, title, startedAt, lastActivityAt, endedAt, metadata)

Typical endpoint-specific error codes:

• MEMORY_SESSION_DISABLED (403)
• INVALID_REQUEST (400)

POST /api/sdk/v1/sessions/checkpoint

Append a checkpoint/event to an active session.

Feature gate: MEMORY_SESSION_ENABLED must be on (403 MEMORY_SESSION_DISABLED when off).

Request:

{
  "sessionId": "sess_abc123",
  "content": "User confirmed we can promote canary after metrics pass.",
  "role": "assistant",
  "kind": "summary",
  "tokenCount": 320,
  "turnIndex": 8,
  "isMeaningful": true,
  "scope": {
    "tenantId": "acme-prod",
    "userId": "user_123",
    "projectId": "github.com/acme/platform"
  }
}

Response data:

• sessionId
• eventId
• message
• event (id, sessionId, role, kind, content, tokenCount, turnIndex, isMeaningful, createdAt)

Typical endpoint-specific error codes:

• MEMORY_SESSION_DISABLED (403)
• SESSION_ID_REQUIRED (400)
• SESSION_CONTENT_REQUIRED (400)
• SESSION_NOT_FOUND (404)
• SESSION_NOT_ACTIVE (409)

POST /api/sdk/v1/sessions/end

End an active session with final status closed or compacted.

Feature gate: MEMORY_SESSION_ENABLED must be on (403 MEMORY_SESSION_DISABLED when off).

Request:

{
  "sessionId": "sess_abc123",
  "status": "compacted",
  "scope": {
    "tenantId": "acme-prod",
    "userId": "user_123",
    "projectId": "github.com/acme/platform"
  }
}

Response data:

• sessionId
• message
• session (same shape as sessions/start)

Typical endpoint-specific error codes:

• MEMORY_SESSION_DISABLED (403)
• SESSION_ID_REQUIRED (400)
• INVALID_SESSION_STATUS (400)
• SESSION_NOT_FOUND (404)
• SESSION_NOT_ACTIVE (409)

GET /api/sdk/v1/sessions/{sessionId}/snapshot

Fetch latest snapshot for a session.

Feature gate: MEMORY_SESSION_ENABLED must be on (403 MEMORY_SESSION_DISABLED when off).

Query params (optional scope routing):

• tenantId
• userId
• projectId

Example:

GET /api/sdk/v1/sessions/sess_abc123/snapshot?tenantId=acme-prod&userId=user_123&projectId=github.com/acme/platform
Authorization: Bearer mem_xxx

Response data:

• sessionId
• message
• snapshot (id, sessionId, slug, sourceTrigger, transcriptMd, messageCount, createdAt)

Typical endpoint-specific error codes:

• MEMORY_SESSION_DISABLED (403)
• SESSION_NOT_FOUND (404)
• SESSION_SNAPSHOT_NOT_FOUND (404)

POST /api/sdk/v1/skills/files/upsert

Create or update a scoped skill file.

Request:

{
  "path": ".agents/skills/review/SKILL.md",
  "content": "---\nname: review\n---\nUse strict checks.",
  "scope": {
    "tenantId": "acme-prod",
    "userId": "user_123",
    "projectId": "github.com/acme/platform"
  }
}

Response data:

• skillFile
• created
• message

POST /api/sdk/v1/skills/files/list

List scoped skill files.

Request:

{
  "limit": 100,
  "scope": {
    "tenantId": "acme-prod",
    "userId": "user_123",
    "projectId": "github.com/acme/platform"
  }
}

Response data:

• skillFiles[]
• count

POST /api/sdk/v1/skills/files/delete

Soft-delete a scoped skill file.

Request:

{
  "path": ".agents/skills/review/SKILL.md",
  "scope": {
    "tenantId": "acme-prod",
    "userId": "user_123",
    "projectId": "github.com/acme/platform"
  }
}

Response data:

• path
• deleted: true
• message

POST /api/sdk/v1/skills/files/promote

Promote a session snapshot into a procedural skill file.

Feature gate: MEMORY_PROCEDURAL_ENABLED must be on (403 MEMORY_PROCEDURAL_DISABLED when off).

Request:

{
  "sessionId": "sess_abc123",
  "snapshotId": "snap_987",
  "path": ".agents/skills/oncall-incident/SKILL.md",
  "title": "On-call incident response procedure",
  "procedureKey": "incident-response-v1",
  "maxSteps": 8,
  "scope": {
    "tenantId": "acme-prod",
    "userId": "user_123",
    "projectId": "github.com/acme/platform"
  }
}

Status is:

• 201 when a new skill file is created
• 200 when an existing file is updated

Response data:

• skillFile
• created
• source (sessionId, snapshotId, snapshotSlug, snapshotCreatedAt)
• message

Typical endpoint-specific error codes:

• MEMORY_PROCEDURAL_DISABLED (403)
• SESSION_ID_REQUIRED (400)
• SKILL_FILE_PATH_REQUIRED (400)
• SESSION_SNAPSHOT_NOT_FOUND (404)

Graph Endpoint Contracts

GET|POST /api/sdk/v1/graph/status

Read graph health + rollout metrics for current scope.

GET query params:

• topNodesLimit
• tenantId
• userId
• projectId

POST body:

{
  "topNodesLimit": 10,
  "scope": {
    "tenantId": "acme-prod",
    "userId": "user_123",
    "projectId": "github.com/acme/platform"
  }
}

Response data includes:

• enabled, flags
• health (ok | schema_missing)
• tables, counts
• rollout
• shadowMetrics
• qualityGate
• alarms
• topConnectedNodes
• recentErrors
• sampledAt
• scope (resolved scope echo)

POST /api/sdk/v1/graph/trace

Trace retrieval behavior and graph expansion decisions.

Request is similar to context/get, but defaults differ:

• strategy default: policy default (baseline for lexical policy, hybrid_graph for hybrid policy)
• limit default: 10

graph/trace currently accepts legacy strategy literals (baseline, hybrid_graph) for direct diagnostics parity. Use context/get with lexical|hybrid in new client integrations.

Response data includes:

• mode, includeRules, query
• strategy: { requested, applied }
• trace: rollout/fallback/candidate metrics
  • includes retrieval policy diagnostics:
    • retrievalPolicyDefaultStrategy
    • retrievalPolicyAppliedStrategy
    • retrievalPolicySelection
    • retrievalPolicyReadyForDefaultOn
    • retrievalPolicyBlockerCodes
• tiers: rule/working/long-term ID lists
• recall[]: rank + source (baseline or graph_expansion) + graph explainability
• rules[], memories[]

GET|POST|PATCH /api/sdk/v1/graph/rollout

Manage rollout mode.

GET:

• reads current rollout + quality gate + metrics summary
• evaluates rollout plan and optional autopilot promotion

POST / PATCH request:

{
  "mode": "canary",
  "scope": {
    "tenantId": "acme-prod",
    "projectId": "github.com/acme/platform"
  }
}

mode must be one of:

• off
• shadow
• canary

Canary gate behavior:

• POST/PATCH mode=canary can return 409 with CANARY_ROLLOUT_BLOCKED
• error details includes reasonCodes, qualityStatus, and windowHours

Successful response data includes:

• rollout
• shadowMetrics
• qualityGate
• rolloutPlan
  • recommendedMode
  • defaultBehaviorDecision
  • readyForDefaultOn
  • blockerCodes
  • baseline (gap-to-goal metrics)
  • slo thresholds and sample requirements
  • autopilot (enabled, applied)
• retrievalPolicy
  • defaultStrategy
  • readyWindowStreak
  • lastDecision
  • lastEvaluatedAt
  • updatedAt
  • updatedBy
• scope

Health Contract

GET /api/sdk/v1/health

Response data:

{
  "status": "ok",
  "service": "memories-sdk",
  "schemaVersion": "2026-02-11"
}

Management Endpoint Contracts

/api/sdk/v1/management/tenant-overrides is the primary tenant override API.

GET|POST|DELETE /api/sdk/v1/management/keys

• GET: current key status plus key inventory (hasKey, keyCount, activeKeyCount, primary preview timestamps, and keys[])
• POST: create an additional key with expiresAt body (returns new apiKey once)
• DELETE: revoke all keys, or revoke one key when keyId query param is provided

POST request:

{
  "expiresAt": "2027-01-01T00:00:00.000Z"
}

DELETE examples:

DELETE /api/sdk/v1/management/keys
DELETE /api/sdk/v1/management/keys?keyId=3c02d4fd-6f3d-4f7f-a190-9dc7527dd0b3

GET|POST|DELETE /api/sdk/v1/management/tenant-overrides

• GET: list AI SDK Projects (tenantId mappings)
• POST: upsert AI SDK Project mapping
• DELETE: disable AI SDK Project mapping by tenantId query param

POST request:

{
  "tenantId": "acme-prod",
  "mode": "provision",
  "metadata": {
    "region": "us-east-2"
  }
}

Attach mode request:

{
  "tenantId": "acme-prod",
  "mode": "attach",
  "tursoDbUrl": "libsql://example.turso.io",
  "tursoDbToken": "token",
  "tursoDbName": "example"
}

DELETE example:

DELETE /api/sdk/v1/management/tenant-overrides?tenantId=acme-prod

GET /api/sdk/v1/embeddings/models

Resolve available embedding models and the selected/default model for a scope.

Query params:

• tenantId
• projectId
• embeddingModel (optional requested override)

Response data:

• models[]
• config (selectedModelId, source, workspaceDefaultModelId, projectOverrideModelId, allowlistModelIds)

GET /api/sdk/v1/management/embeddings/usage

Read aggregated embedding usage + cost for management dashboards and billing reconciliation.

Query params:

• usageMonth (YYYY-MM-DD, defaults to current month start)
• tenantId
• projectId
• limit

Response data:

• usageMonth
• summary (requestCount, token/cost totals)
• breakdown[] (grouped by tenant/project/model/provider)

GET|POST /api/sdk/v1/management/embeddings/backfill

Manage backfill progress and control execution.

• GET: read scope status
• POST action=run: execute batch
• POST action=pause|resume: toggle backfill state

GET /api/sdk/v1/management/embeddings/observability

Read operational snapshot with queue/worker/backfill/retrieval/cost health and SLO-based alarms.

Query params:

• tenantId
• projectId
• userId
• modelId
• usageMonth
• windowHours (1..168)

Response data includes:

• queue, worker, backfill, retrieval, cost
• worker.topErrorCodes[] (top 5 error_code values in the window; includes graph relationship signals such as GRAPH_RELATIONSHIP_SYNC_FAILED and GRAPH_RELATIONSHIP_PARTIAL_DEGRADE)
• slos
• alarms[]
• health (healthy | degraded | critical)

GET /api/sdk/v1/management/memory/observability

Read lifecycle health snapshot for memory creation, compaction, consolidation, and contradiction trends.

Query params:

• tenantId
• projectId
• userId
• windowHours (1..336)

Response data includes:

• lifecycle (created/updated/deleted/active/total counts)
• compaction (trigger mix, checkpoint coverage)
• consolidation (run totals + conflict rate)
• contradictions (window totals + daily trend)
• alarms[]
• health (healthy | degraded | critical)

POST /api/sdk/v1/management/memory/eval/replay

Run deterministic replay/eval scoring for extraction quality, compaction retention, and trigger matching.

Request:

{
  "tenantId": "acme-prod",
  "projectId": "github.com/acme/platform",
  "passCriteria": {
    "extractionF1": 0.7,
    "compactionRetention": 0.85,
    "triggerAccuracy": 0.9,
    "casePassRatio": 0.85
  },
  "scenarios": [
    {
      "id": "release-1",
      "extraction": {
        "expected": ["Always snapshot before reset"],
        "observed": ["Always snapshot before reset"]
      },
      "trigger": {
        "expected": "semantic",
        "observed": "semantic"
      }
    }
  ]
}

Response data includes:

• scope (tenant/project/user echo)
• summary (case counts, aggregate scores, pass/warn/fail)
• scenarios[] (per-case extraction/compaction/trigger metrics)

Memory Lifecycle Feature Flags

Default rollout posture:

• MEMORY_SESSION_ENABLED=true
• MEMORY_COMPACTION_ENABLED=true
• MEMORY_CONSOLIDATION_ENABLED=true
• MEMORY_PROCEDURAL_ENABLED=true
• MEMORY_OPENCLAW_FILE_MODE_ENABLED=false (opt-in)

When disabled, affected endpoints return 403 with a typed flag code:

• MEMORY_SESSION_DISABLED
• MEMORY_COMPACTION_DISABLED
• MEMORY_CONSOLIDATION_DISABLED
• MEMORY_PROCEDURAL_DISABLED

cURL Quick Reference

Context

curl -sS https://memories.sh/api/sdk/v1/context/get \
  -H "Authorization: Bearer $MEMORIES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query":"deployment",
    "scope":{"tenantId":"acme-prod","userId":"user_123","projectId":"github.com/acme/platform"}
  }'

Add memory

curl -sS https://memories.sh/api/sdk/v1/memories/add \
  -H "Authorization: Bearer $MEMORIES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content":"Always run smoke tests before deploy",
    "type":"rule",
    "scope":{"tenantId":"acme-prod","userId":"user_123","projectId":"github.com/acme/platform"}
  }'

Bulk forget (dry run)

curl -sS https://memories.sh/api/sdk/v1/memories/bulk-forget \
  -H "Authorization: Bearer $MEMORIES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters":{"types":["note"],"olderThanDays":90},
    "dryRun":true,
    "scope":{"tenantId":"acme-prod","userId":"user_123"}
  }'

Vacuum

curl -sS https://memories.sh/api/sdk/v1/memories/vacuum \
  -H "Authorization: Bearer $MEMORIES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope":{"tenantId":"acme-prod","userId":"user_123"}
  }'

Graph rollout status

curl -sS "https://memories.sh/api/sdk/v1/graph/rollout?tenantId=acme-prod" \
  -H "Authorization: Bearer $MEMORIES_API_KEY"

Compatibility Notes

• Prefer transport: "sdk_http" (or "auto") in SDK clients.
• MCP JSON-RPC (/api/mcp) remains available for MCP-native clients.
• Breaking SDK HTTP changes will ship under a new prefix (/api/sdk/v2/*).