> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memorycrystal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Memory endpoints

> The HTTP endpoints that capture, recall, search, trace, and inspect Memory Crystal state.

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:**

```json theme={"system"}
{
  "channel": "claude-code",
  "userId": "user_123"
}
```

**Response:**

```json theme={"system"}
{
  "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:**

```json theme={"system"}
{
  "query": "authentication implementation details",
  "limit": 5,
  "channel": "claude-code",
  "agentId": "assistant",
  "includeGraphContext": true
}
```

**Response:**

```json theme={"system"}
{
  "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

<Note>
  **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.
</Note>

**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:**

```json theme={"system"}
{
  "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:**

```json theme={"system"}
{
  "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:**

```json theme={"system"}
{
  "limit": 20,
  "channel": "claude-code",
  "startDate": "2026-06-01",
  "endDate": "2026-06-30"
}
```

**Response:**

```json theme={"system"}
{
  "messages": [
    { "timestamp": 1681234567890, "role": "user", "text": "..." }
  ]
}
```

### Memory Management

#### `POST /api/mcp/capture`

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

**Request:**

```json theme={"system"}
{
  "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:**

```json theme={"system"}
{
  "id": "mem_456",
  "embedding": [0.12, -0.45, ...],
  "createdAt": 1681234567890
}
```

#### `POST /api/mcp/checkpoint`

Mark a session milestone.

**Request:**

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

**Response:**

```json theme={"system"}
{
  "id": "ckpt_789",
  "timestamp": 1681234567890
}
```

#### `POST /api/mcp/trace`

Retrieve the original conversation context for a memory.

**Request:**

```json theme={"system"}
{
  "memoryId": "mem_123"
}
```

**Response:**

```json theme={"system"}
{
  "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:**

```json theme={"system"}
{
  "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:

1. **Session start:** `POST /api/mcp/wake` → prime context
2. **Before work:** `POST /api/mcp/recall` with relevant query → semantic context
3. **After response:** `POST /api/mcp/capture` with extracted memory
4. **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`