Skip to main content
These endpoints expose the core memory surface over authenticated HTTP. All requests require an Authorization: Bearer <your-api-key> header. See Authentication for details.

​
POST /api/mcp/capture

Create a memory directly. Use this to store decisions, facts, lessons, and anything else worth keeping outside of an active conversation.

​
Request body

​
title
string
required
Short, descriptive title for the memory. Make it specific and searchable — for example, "Chose PostgreSQL over SQLite — needs concurrent write support".
​
content
string
required
The full memory content. Include context: what was decided, why, what alternatives were considered.
​
store
string
default:"semantic"
Memory store. One of: sensory, episodic, semantic, procedural, prospective.
​
category
string
default:"fact"
Memory category. One of: decision, lesson, person, rule, event, fact, goal, workflow, conversation.
​
tags
string[]
Tags for filtering and recall. Use 3–6 tags mixing specific and general terms.
​
confidence
number
default:"0.7"
Confidence in the memory’s accuracy, from 0 to 1. Higher values indicate well-established facts.

​
Response

​
memoryId
string
Unique ID of the created memory.
​
created
boolean
true when the memory was successfully written.
curl -X POST https://your-deployment.convex.site/api/mcp/capture \
  -H "Authorization: Bearer mc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Deploy uses docker-compose on DigitalOcean",
    "content": "Production deploys run via docker-compose on a DigitalOcean droplet. Use npm run deploy:prod which wraps docker-compose up -d --build.",
    "store": "procedural",
    "category": "workflow",
    "tags": ["deploy", "docker", "production"]
  }'

{
  "memoryId": "mem_abc123",
  "created": true
}

​
POST /api/mcp/recall

Run hybrid recall over your memory — both short-term message history and long-term extracted memories. Returns ranked results using vector similarity, BM25 text matching, freshness, and graph connectivity.

​
Request body

​
query
string
required
Natural-language question or keyword phrase to search for.
​
mode
string
default:"general"
Recall mode. One of: general, decision, project, people, workflow, conversation. Influences which stores and categories are weighted higher.
​
limit
number
default:"10"
Maximum number of results to return.
​
categories
string[]
Filter results to specific categories. Example: ["decision", "rule"].
​
stores
string[]
Filter results to specific stores. Example: ["semantic", "procedural"].

​
Response

An array of memory objects, each containing:
​
memoryId
string
Unique memory ID.
​
title
string
Memory title.
​
content
string
Full memory content.
​
store
string
Memory store (semantic, episodic, etc.).
​
category
string
Memory category (decision, fact, etc.).
​
tags
string[]
Associated tags.
​
score
number
Composite relevance score.
curl -X POST https://your-deployment.convex.site/api/mcp/recall \
  -H "Authorization: Bearer mc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "why did we choose Convex over Supabase",
    "mode": "decision",
    "limit": 5
  }'

​
POST /api/mcp/search-messages

Search short-term message history using hybrid BM25 and vector search. Returns verbatim message records from recent conversations.

​
Request body

​
query
string
required
Text to search for in conversation history.
​
limit
number
default:"10"
Maximum number of messages to return.

​
Response

An array of message objects, each containing:
​
messageId
string
Unique message ID.
​
content
string
Verbatim message content.
​
role
string
user or assistant.
​
createdAt
number
Unix timestamp (milliseconds) when the message was captured.
curl -X POST https://your-deployment.convex.site/api/mcp/search-messages \
  -H "Authorization: Bearer mc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "docker deployment DigitalOcean",
    "limit": 10
  }'

​
POST /api/mcp/wake

Session startup briefing. Call this at the start of a new session to receive a summary of recent context, active goals, pending decisions, and any guardrails your agent should respect.

​
Request body

​
channel
string
Channel identifier for the current session. Scopes the briefing to the right workspace or agent lane.

​
Response

​
briefing
string
Formatted briefing text ready to inject into your agent’s system prompt. Includes recent context, active goals, standing rules, and recent decisions from previous sessions.
curl -X POST https://your-deployment.convex.site/api/mcp/wake \
  -H "Authorization: Bearer mc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "my-agent:session-42"
  }'

​
POST /api/mcp/checkpoint

Save a session checkpoint — a labelled snapshot of what was accomplished. Useful at the end of a significant working session.

​
Request body

​
label
string
required
A short summary of what was done and what comes next. Example: "Finished auth flow. Next: wire up billing webhooks.".
curl -X POST https://your-deployment.convex.site/api/mcp/checkpoint \
  -H "Authorization: Bearer mc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Migrated KB import to bulk-insert endpoint. Next: test backfill status polling."
  }'

​
GET /api/mcp/stats

Retrieve usage statistics for your account — total memories by store, message counts, and Knowledge Base counts. 
curl https://your-deployment.convex.site/api/mcp/stats \
  -H "Authorization: Bearer mc_your_api_key"

{
  "totalMemories": 1284,
  "byStore": {
    "semantic": 842,
    "episodic": 201,
    "procedural": 156,
    "prospective": 63,
    "sensory": 22
  },
  "totalMessages": 9431,
  "knowledgeBases": 3
}

​
POST /api/mcp/forget

Archive or permanently delete a memory.

​
Request body

​
memoryId
string
required
The ID of the memory to remove. Obtain this from a prior recall or capture response.
​
permanent
boolean
default:"false"
When false (default), the memory is soft-deleted (archived). When true, the memory is permanently removed. Use with caution — permanent deletion cannot be undone.
curl -X POST https://your-deployment.convex.site/api/mcp/forget \
  -H "Authorization: Bearer mc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "memoryId": "mem_abc123",
    "permanent": false
  }'
Setting permanent: true removes the memory and all its graph connections. This action cannot be undone. Use permanent: false (the default) to archive instead.