> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thrindex.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Tool Reference
> Full parameter documentation and example calls for all five Thrindex MCP tools.
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
| Parameter | Type | Required | Default | Description |
| ------------ | ------- | -------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `content` | string | yes | — | The information to store. Be specific and self-contained — each memory should make sense without surrounding context. Max 8 KB. |
| `agent_id` | string | no | `"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_id` | string | no | `"default"` | Identifier for the user this memory belongs to. Use a stable, unique value per person, e.g. `"user-123"` or `"alice"`. |
| `confidence` | float | no | `1.0` | Your confidence in this information's accuracy, `0.0`–`1.0`. Use lower values for inferred or uncertain facts. |
| `extract` | boolean | no | `true` | When `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
```json theme={null}
{
"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
| Parameter | Type | Required | Default | Description |
| -------------- | ------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query` | string | yes | — | 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_id` | string | no | — | Restrict results to memories written by this agent. Leave empty to search across all agents. |
| `user_id` | string | no | — | Restrict results to memories belonging to this user. Leave empty to search across all users. |
| `k` | integer | no | `10` | Maximum number of memories to return. Range: `1`–`50`. |
| `task_context` | string | no | — | 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
```json theme={null}
{
"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
| Parameter | Type | Required | Default | Description |
| ---------- | ------- | -------- | ------- | -------------------------------------------------------------------------------------------------- |
| `agent_id` | string | no | — | Filter to memories written by this agent. Leave empty to list all agents. |
| `user_id` | string | no | — | Filter to memories belonging to this user. Leave empty to list all users. |
| `limit` | integer | no | `20` | Number of memories to return per page. Range: `1`–`50`. |
| `cursor` | string | no | — | Opaque cursor from a previous `list_memories` response. Omit to start from the most recent memory. |
### Example tool call
```json theme={null}
{
"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
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------------------------------- |
| `id` | string | yes | The UUID of the memory to retrieve. |
### Example tool call
```json theme={null}
{
"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
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | --------------------------------- |
| `id` | string | yes | The UUID of the memory to delete. |
### Example tool call
```json theme={null}
{
"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
| Message | Cause |
| --------------------------------------------- | ------------------------------------------------------------------------------------ |
| `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 required` | `store_memory` was called without a `content` argument. |
| `Memory not found: ` | The ID does not exist or belongs to a different organization. |
| `confidence must be between 0.0 and 1.0` | `confidence` 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.