API Reference

Engram exposes 6 tools via the Model Context Protocol (MCP). All tools are accessed through the /mcp endpoint using Streamable HTTP transport.

All requests require an Authorization: Bearer engram_sk_live_... header.

create_conversation

Create a new conversation to store messages in.

Parameters

Response

{
  "conversation_id": "conv_V1StGXR8_Z5jdHi6B-myT"
}

Example

create_conversation
  title: "Weekly standup — March 23"
  agent_id: "support-bot-v2"
  tags: ["standup", "engineering"]
  metadata: { "team": "platform" }

append_messages

Append messages to a conversation. Messages are stored verbatim and automatically chunked and embedded for semantic search.

Parameters

MessageInput:

Response

{
  "appended": 2,
  "message_ids": [
    "msg_V1StGXR8_Z5jdHi6B-myT",
    "msg_K2RtHYS9_A6keFj7C-nzU"
  ]
}

Example

append_messages
  conversation_id: "conv_V1StGXR8_Z5jdHi6B-myT"
  messages:
    - role: "user"
      content: "Can you look up the customer's billing history?"
    - role: "assistant"
      content: "I'll check that now."
    - role: "tool"
      content: '{"invoices": [{"id": "inv_123", "amount": 99.00}]}'
      tool_name: "lookup_billing"
      tool_call_id: "call_abc"
    - role: "assistant"
      content: "They have one invoice for $99.00."

What happens on append

1. Messages are inserted into the database with sequential ordering
2. New messages are grouped into overlapping chunks (window of 5 messages, stride of 3)
3. Each chunk is embedded using bge-base-en-v1.5 (768 dimensions)
4. Vectors are upserted to the search index with conversation and organization metadata

search

Semantic search across all stored conversations. Returns matching chunk snippets with relevance scores. Each result contains the chunk_text window that Vectorize matched on, clipped to snippet_chars characters — call get_conversation with the returned start_sequence / end_sequence if you need the full structured messages.

Parameters

Response

{
  "results": [
    {
      "chunk_id": "chk_V1StGXR8_Z5jdHi6B-myT",
      "conversation_id": "conv_abc123",
      "chunk_text": "[user]: Can you look up the billing?\n[assistant]: I'll check that now.\n...",
      "score": 0.89,
      "start_sequence": 1,
      "end_sequence": 5
    }
  ],
  "total": 1
}

Example

search
  query: "customer billing lookup"
  limit: 5

Results are ranked by cosine similarity. The chunk_text field contains the same [role]: content window that Vectorize matched on — enough context to decide which results are worth loading in full. If you need structured messages (role, tool_name, metadata, etc.), call get_conversation with the returned conversation_id and compute a message offset from start_sequence.

Why not return both? Earlier versions of the API returned chunk_text and the full Message[] for the same window, which doubled the response size and routinely pushed search responses past 10k tokens. The response now carries the chunk snippet only; structured messages are opt-in via get_conversation.

get_conversation

Retrieve a conversation with its full verbatim messages. Supports pagination for long conversations.

Parameters

Response

{
  "conversation": {
    "id": "conv_V1StGXR8_Z5jdHi6B-myT",
    "title": "Weekly standup — March 23",
    "agent_id": "support-bot-v2",
    "tags": ["standup", "engineering"],
    "metadata": { "team": "platform" },
    "message_count": 42,
    "created_at": "2026-03-23T10:00:00Z",
    "updated_at": "2026-03-23T10:30:00Z"
  },
  "messages": [
    {
      "id": "msg_xyz",
      "role": "user",
      "content": "Let's start with blockers...",
      "sequence": 1,
      "created_at": "2026-03-23T10:00:01Z"
    }
  ]
}

Example

get_conversation
  conversation_id: "conv_V1StGXR8_Z5jdHi6B-myT"
  message_limit: 50
  message_offset: 0

list_conversations

List conversations with filtering and sorting options.

Parameters

Response

{
  "conversations": [
    {
      "id": "conv_V1StGXR8_Z5jdHi6B-myT",
      "title": "Weekly standup — March 23",
      "agent_id": "support-bot-v2",
      "tags": ["standup"],
      "message_count": 42,
      "updated_at": "2026-03-23T10:30:00Z"
    }
  ],
  "total": 1
}

Example

list_conversations
  agent_id: "support-bot-v2"
  tags: ["engineering"]
  sort: "message_count"
  order: "desc"
  limit: 10

delete_conversation

Permanently delete a conversation and all its messages, chunks, and vector embeddings.

Parameters

Response

{
  "deleted": true
}

Returns an error if the conversation is not found or doesn’t belong to your organization.

Error Responses

When a tool encounters an error, it returns:

{
  "error": "Conversation not found"
}

Common errors: