Memory endpoints - Memory Crystal

These are the HTTP doors for the memory side of the system.

What this means in practice

Important endpoint families include:

capture
recall
search-messages
recent-messages
wake
checkpoint
trace
stats

Important related tool surfaces include:

crystal_recall
crystal_search_messages
crystal_recent
crystal_debug_recall

How it actually works

Key repo surfaces:

convex/crystal/mcp.ts
packages/mcp-server/README.md
mcp-server/README.md

The modern and legacy MCP packages both depend on this underlying memory/API surface, even though they package it differently.

Endpoint Reference

Session Initialization

`POST /api/mcp/wake`

Fetch the last session summary and recent messages to initialize a new session. Request:

{
  "channel": "claude-code",
  "userId": "user_123"
}

Response:

{
  "lastSessionSummary": "Yesterday's meeting covered Q2 roadmap...",
  "recentMessages": [
    { "timestamp": 1681234567890, "role": "user", "text": "..." },
    { "timestamp": 1681234568000, "role": "assistant", "text": "..." }
  ]
}

Memory Recall

`POST /api/mcp/recall`

Vector search over memories by semantic query. Request:

{
  "query": "authentication implementation details",
  "limit": 5,
  "channel": "claude-code",
  "agentId": "assistant",
  "includeGraphContext": true
}

Response:

{
  "memories": [
    {
      "id": "mem_123",
      "title": "API key hashing strategy",
      "content": "Keys are hashed with SHA256 before storage...",
      "store": "semantic",
      "category": "decision",
      "relevance": 0.89,
      "createdAt": 1681234567890
    }
  ]
}

Optional request fields:

channel — channel/scope context, including peer-scoped or shared-main values
agentId — agent identifier used when resolving knowledge-base visibility for mixed private/shared deployments
includeGraphContext — defaults to true; set to false when temporarily prioritizing lower latency over linked entity/relation context

Peer-first fallback (new in 0.7.15). If channel is omitted on a peer-facing call, recall fails-closed on any knowledge base with a concrete peer scope. Previously the guard silently upgraded unscoped callers to management-level visibility. Always pass the peer channel (e.g. peer-coach:511172388) from a peer session.

Behavior notes:

the live MCP recall path computes one query embedding and reuses it across semantic memory recall and message-search evidence
identical repeated HTTP recall requests can reuse the short-lived query embedding cache
KB results are merged after normal memory recall, with agent/scope-aware visibility rules
compact graph context is included by default and omitted only when the caller explicitly sends includeGraphContext: false

Message Search

`POST /api/mcp/search-messages`

Semantic + keyword search over raw message transcripts, optionally bounded to a time window and paged. Use it for questions like “what did X say last month about Y”: pass the topic as query, the peer as channel, and the window via fromMs/toMs (or ISO startDate/endDate). Request:

{
  "query": "rate limit",
  "channel": "claude-code",
  "limit": 50,
  "offset": 0,
  "startDate": "2026-06-01",
  "endDate": "2026-06-30"
}

Parameters:

query (required) — search text.
channel / sessionKey — exact scope. On a multi-client (peer) account, always pass the peer channel — search is channel-isolated and never crosses clients.
limit — 1–100 (default 10).
offset — skip N ranked results for pagination.
Time window — fromMs/toMs (epoch ms) or startDate/endDate (ISO date/datetime); sinceMs, before, after are accepted aliases. A plausible seconds-precision value is auto-upscaled to ms.

Response:

{
  "messages": [ { "role": "user", "content": "...", "timestamp": 1681234567890, "channel": "claude-code", "score": 3 } ],
  "turns": [ { "timestamp": 1681234567890, "messages": [ /* ... */ ] } ],
  "pagination": { "limit": 50, "offset": 0, "returned": 50, "hasMore": true, "nextOffset": 50 },
  "window": { "fromMs": 1780272000000, "toMs": 1782777600000 }
}

Page with offset: nextOffset while pagination.hasMore is true. A short page means you have reached the end — do not assert a window is empty from one page.

`POST /api/mcp/recent-messages`

Fetch the most recent messages in time order without vector-search cost. Accepts the same channel scope and time window (fromMs/toMs or startDate/endDate) as search-messages; order may be "chronological" (default) or "newest". Request:

{
  "limit": 20,
  "channel": "claude-code",
  "startDate": "2026-06-01",
  "endDate": "2026-06-30"
}

Response:

{
  "messages": [
    { "timestamp": 1681234567890, "role": "user", "text": "..." }
  ]
}

Memory Management

`POST /api/mcp/capture`

Store a new memory (typically called after AI response completes). Request:

{
  "title": "Decided to use Convex for state management",
  "content": "Convex mutations provide automatic retries and transactional guarantees...",
  "store": "semantic",
  "category": "decision",
  "channel": "claude-code"
}

Response:

{
  "id": "mem_456",
  "embedding": [0.12, -0.45, ...],
  "createdAt": 1681234567890
}

`POST /api/mcp/checkpoint`

Mark a session milestone. Request:

{
  "label": "Completed authentication module",
  "description": "Implemented API key creation, validation, and rate limiting. Next: write tests."
}

Response:

{
  "id": "ckpt_789",
  "timestamp": 1681234567890
}

`POST /api/mcp/trace`

Retrieve the original conversation context for a memory. Request:

{
  "memoryId": "mem_123"
}

Response:

{
  "memory": { "id": "mem_123", "title": "...", "content": "..." },
  "sourceConversation": [
    { "role": "user", "text": "How should we handle auth?" },
    { "role": "assistant", "text": "We should hash keys before storage..." }
  ],
  "contextBefore": [...],
  "contextAfter": [...]
}

System

`GET /api/mcp/stats`

Memory store health and usage. Response:

{
  "memoryCount": {
    "byStore": { "semantic": 124, "episodic": 89, "procedural": 34 },
    "byCategory": { "decision": 45, "lesson": 38, "fact": 125 }
  },
  "ttlStatus": {
    "free_tier_expires_in_days": 7,
    "messages_stored": 543
  },
  "usage": {
    "tier": "pro",
    "memory_limit": 5000,
    "memories_used": 247,
    "percent_used": 4.94
  }
}

Usage Pattern: Full Turn

Typical agentic flow:

Session start: POST /api/mcp/wake → prime context
Before work: POST /api/mcp/recall with relevant query → semantic context
After response: POST /api/mcp/capture with extracted memory
Optional: POST /api/mcp/checkpoint if turning point reached

For debugging:

Add debugRecallOutput=true query param to recall endpoints to get verbose output including all search results, filtering, and prompt injections
Use POST /api/mcp/trace to understand memory provenance

Common mistakes

assuming the endpoint list is the whole behavior without reading the surrounding logic in mcp.ts
mixing HTTP endpoints and MCP tool names without explaining the relationship
ignoring auth/rate-limit behavior when describing the API surface

Source of truth

Primary files behind this page:

convex/crystal/mcp.ts
packages/mcp-server/README.md
mcp-server/README.md

​What this means in practice

​How it actually works

​Endpoint Reference

​Session Initialization

​POST /api/mcp/wake

​Memory Recall

​POST /api/mcp/recall

​Message Search

​POST /api/mcp/search-messages

​POST /api/mcp/recent-messages

​Memory Management

​POST /api/mcp/capture

​POST /api/mcp/checkpoint

​POST /api/mcp/trace

​System

​GET /api/mcp/stats

​Usage Pattern: Full Turn

​Common mistakes

​Source of truth

What this means in practice

How it actually works

Endpoint Reference

Session Initialization

`POST /api/mcp/wake`

Memory Recall

`POST /api/mcp/recall`

Message Search

`POST /api/mcp/search-messages`

`POST /api/mcp/recent-messages`

Memory Management

`POST /api/mcp/capture`

`POST /api/mcp/checkpoint`

`POST /api/mcp/trace`

System

`GET /api/mcp/stats`

Usage Pattern: Full Turn

Common mistakes

Source of truth