Skip to main content
Thrindex exposes five tools over MCP. Your AI client calls these automatically — you do not need to define them yourself. This page documents every parameter and the format of each tool’s response so you can write effective system prompts and agent instructions.

​
store_memory

Persist a fact, preference, or piece of context for a user. Required scope: memory:write When to call: After learning something meaningful about a user — their preferences, goals, past decisions, or any context worth recalling later. Also call it when explicitly asked to “remember” something.

​
Parameters

ParameterTypeRequiredDefaultDescription
contentstringyes—The information to store. Be specific and self-contained — each memory should make sense without surrounding context. Max 8 KB.
agent_idstringno"mcp-client"Identifier for the agent storing this memory. Use a consistent value for the same agent across sessions, e.g. "claude-desktop" or "customer-support-bot".
user_idstringno"default"Identifier for the user this memory belongs to. Use a stable, unique value per person, e.g. "user-123" or "alice".
confidencefloatno1.0Your confidence in this information’s accuracy, 0.0–1.0. Use lower values for inferred or uncertain facts.
extractbooleannotrueWhen true, the cognition worker runs LLM extraction to transform raw content into clean, discrete facts before storage. Set to false to store content verbatim with no LLM call.

​
Example tool call

{
  "name": "store_memory",
  "arguments": {
    "content": "User prefers weekly email digests over push notifications.",
    "agent_id": "claude-desktop",
    "user_id": "alice",
    "confidence": 1.0
  }
}

​
Tool result

Memory queued for processing.
ID: 3f2e1d0c-1234-5678-abcd-ef0123456789
Status: queued

The memory will be indexed and available for search within a few seconds.
The memory is processed asynchronously. It will be available for search within a few seconds of the tool call returning. Pass extract=false to skip LLM fact extraction and store content verbatim — useful when you already control the phrasing of the fact.

​
search_memories

Search for relevant memories using semantic similarity. Required scope: memory:read When to call: At the start of a conversation to load user context, before answering questions that might benefit from past context, or when asked “do you remember…”. Results are ranked by a combination of semantic relevance, importance, and recency.

​
Parameters

ParameterTypeRequiredDefaultDescription
querystringyes—Natural language description of what you are looking for. Can be a question, a topic, or a description of the context you need. Max 2048 characters.
agent_idstringno—Restrict results to memories written by this agent. Leave empty to search across all agents.
user_idstringno—Restrict results to memories belonging to this user. Leave empty to search across all users.
kintegerno10Maximum number of memories to return. Range: 1–50.
task_contextstringno—Optional description of what you are currently trying to accomplish. Used to improve ranking beyond pure semantic similarity. Example: "composing a weekly digest email".

​
Example tool call

{
  "name": "search_memories",
  "arguments": {
    "query": "how does the user want to receive updates",
    "agent_id": "claude-desktop",
    "user_id": "alice",
    "k": 5,
    "task_context": "composing a notification preferences summary"
  }
}

​
Tool result

Found 2 memories (latency: 38ms, cache_hit: false):

1. [score: 0.934 | importance: 0.82]
   ID: 3f2e1d0c-1234-5678-abcd-ef0123456789
   Content: User prefers weekly email digests over push notifications.
   Agent: claude-desktop | User: alice
   Created: 2026-05-24T17:00:00Z

2. [score: 0.871 | importance: 0.74]
   ID: 9a8b7c6d-abcd-1234-5678-ef0123456789
   Content: User unsubscribed from marketing emails in March 2026.
   Agent: claude-desktop | User: alice
   Created: 2026-05-20T09:15:00Z
The score field is a multi-signal fusion score — use it to compare results within a single response, not across different queries.

​
list_memories

List memories in reverse-chronological order with cursor-based pagination. Required scope: memory:read When to call: When you need an overview of all stored memories for a user or agent, or when you want to browse by recency rather than semantic relevance.

​
Parameters

ParameterTypeRequiredDefaultDescription
agent_idstringno—Filter to memories written by this agent. Leave empty to list all agents.
user_idstringno—Filter to memories belonging to this user. Leave empty to list all users.
limitintegerno20Number of memories to return per page. Range: 1–50.
cursorstringno—Opaque cursor from a previous list_memories response. Omit to start from the most recent memory.

​
Example tool call

{
  "name": "list_memories",
  "arguments": {
    "agent_id": "claude-desktop",
    "user_id": "alice",
    "limit": 10
  }
}

​
Tool result

Listing 3 memories:

1. ID: 3f2e1d0c-1234-5678-abcd-ef0123456789
   Status: active | Importance: 0.82 | Confidence: 1.00
   Agent: claude-desktop | User: alice
   Created: 2026-05-24T17:00:00Z

2. ID: 9a8b7c6d-abcd-1234-5678-ef0123456789
   Status: active | Importance: 0.74 | Confidence: 1.00
   Agent: claude-desktop | User: alice
   Created: 2026-05-20T09:15:00Z

3. ID: b2c3d4e5-5678-abcd-1234-ef9876543210
   Status: active | Importance: 0.61 | Confidence: 0.90
   Agent: claude-desktop | User: alice
   Created: 2026-05-18T14:30:00Z
When more results are available, the response ends with: 
next_cursor: eyJpZCI6Ii4uLiJ9
Pass that value as cursor in the next call to fetch the next page.
Memory content is intentionally excluded from list results to keep responses concise. Call get_memory with a specific ID to retrieve the full content.

​
get_memory

Retrieve the full content and metadata of a single memory by its ID. Required scope: memory:read When to call: When you have a memory ID from search_memories or list_memories and need its complete record, including the full content field.

​
Parameters

ParameterTypeRequiredDescription
idstringyesThe UUID of the memory to retrieve.

​
Example tool call

{
  "name": "get_memory",
  "arguments": {
    "id": "3f2e1d0c-1234-5678-abcd-ef0123456789"
  }
}

​
Tool result

Memory: 3f2e1d0c-1234-5678-abcd-ef0123456789

Content:
User prefers weekly email digests over push notifications.

Metadata:
  Status: active
  Importance: 0.82
  Confidence: 1.00
  Level: 0
  Agent: claude-desktop
  User: alice
  Source: agent
  Created: 2026-05-24T17:00:00Z
  Updated: 2026-05-24T17:00:00Z
If the memory does not exist or belongs to a different organization, the tool returns an error result: 
Memory not found: 3f2e1d0c-1234-5678-abcd-ef0123456789

​
delete_memory

Delete a memory by its ID. Required scope: memory:delete When to call: When a stored memory is outdated, incorrect, or when the user explicitly asks for it to be removed. This performs a soft delete: the memory’s status is set to deprecated and it is immediately excluded from all future searches. The record is not permanently erased from the database. For permanent erasure (GDPR), use DELETE /v1/memories/{id}?hard=true via the REST API directly.

​
Parameters

ParameterTypeRequiredDescription
idstringyesThe UUID of the memory to delete.

​
Example tool call

{
  "name": "delete_memory",
  "arguments": {
    "id": "3f2e1d0c-1234-5678-abcd-ef0123456789"
  }
}

​
Tool result

Memory 3f2e1d0c-1234-5678-abcd-ef0123456789 has been deleted (soft delete — status set to deprecated).
If the memory does not exist: 
Memory not found: 3f2e1d0c-1234-5678-abcd-ef0123456789

​
Error handling

Tool-level errors (missing scope, validation failures, not found) are returned as tool results with isError: true. Your AI client will receive the error message as text and can explain it to the user or take corrective action. Internal server errors are returned as JSON-RPC errors and surface as a tool failure in the client.

​
Common error messages

MessageCause
API key is missing the memory:write scope.The key used does not have memory:write. Create a new key with the correct scopes.
API key is missing the memory:read scope.The key used does not have memory:read.
API key is missing the memory:delete scope.The key used does not have memory:delete.
Monthly write limit reached.Your plan’s write quota is exhausted. Upgrade your plan in the dashboard.
Monthly search limit reached.Your plan’s search quota is exhausted.
content is requiredstore_memory was called without a content argument.
Memory not found: <id>The ID does not exist or belongs to a different organization.
confidence must be between 0.0 and 1.0confidence argument was out of range.

​
Writing effective system prompts

To get the most out of Thrindex memory tools, include guidance in your agent’s system prompt: 
You have access to five Thrindex memory tools: store_memory, search_memories,
list_memories, get_memory, and delete_memory.

Rules:
- At the start of every conversation, call search_memories with a broad query
  about the user to load relevant context before responding.
- Whenever you learn something meaningful about the user (preferences, goals,
  personal details, past decisions), call store_memory immediately.
- When the user asks you to forget something, call delete_memory with the
  appropriate memory ID.
- Always pass a consistent agent_id (e.g. "my-agent") and the user's stable
  identifier as user_id.
Keep agent_id and user_id consistent across sessions. Changing them creates a separate memory namespace and loses access to previously stored memories.