Alvia MCP server tools

This page lists every tool on Alvia’s MCP server at https://api.alvia.ai/mcp, with its arguments and result. To connect a client, see Connect a coding agent with MCP.

Each tool returns structured content and the same JSON as text. Fields with no value are left out, except inside scope, which always holds all five fields.

Scope arguments

Every tool except recall_by_id, inspect_memory, forget_memory and give_memory_feedback takes five optional scope arguments: organization_id, user_id, application_id, agent_id and team_id. Each is a string of up to 128 characters. Writes use the exact scope; reads filter by the fields sent. See Projects and scope.

Remember

The remember tool stores content for memory formation. Takes the scope arguments.

Argument	Type	Required	Description
`content`	string	Yes	1 to 32,000 characters; at most 1,000 when `infer` is `false`.
`infer`	boolean	No	`true` (default) forms a memory from each fact. `false` stores the content as one memory, as `POST /v1/memories` does.
`occurred_at`	date-time	No	When the content was stated or observed, not in the future. Defaults to now. See Point-in-Time Reasoning and change over time.

{
  "status": "queued",
  "message": "Content queued for memory formation. Discover it later with recall or search_memories."
}

Memories form in the background; find them with recall, search_memories or list_memories. The tool uses writes as described in Limits and allowances.

Context

The context tool returns resolved context for a question. Takes the scope arguments.

Argument	Type	Required	Description
`query`	string	Yes	1 to 1,000 characters.
`occurred_after`	date-time	No	Select the initial match from this time on.
`occurred_before`	date-time	No	Select the initial match before this time.

{
  "status": "available",
  "context": "The Atlas service uses PostgreSQL 17 as its primary database."
}

The bounds select the initial match. Related and contradicting memories used to resolve it can have dates outside that range. See Point-in-Time Reasoning and change over time.

When there is no context for the query yet, the result is { "status": "not_found" }. See Get context.

Recall

The recall tool returns the single best memory for a question. Takes the scope arguments.

Argument	Type	Required	Description
`query`	string	Yes	1 to 1,000 characters.
`occurred_after`	date-time	No	Only memories from this time on.
`occurred_before`	date-time	No	Only memories from before this time.

{
  "status": "active",
  "memory_id": "mem_01K6Y3V9QF2W8H4N7C5X0RZB1D",
  "content": "The Atlas service uses PostgreSQL 17 as its primary database.",
  "category": "decision",
  "is_favorited": false,
  "sentiment": "neutral",
  "occurred_at": "2026-09-23T14:00:00+00:00",
  "ranked_score": 0.9204,
  "scope": {
    "organization_id": null,
    "user_id": null,
    "application_id": null,
    "agent_id": null,
    "team_id": null
  },
  "entities": { "project/Atlas": 0.58, "tool/PostgreSQL 17": 0.42 }
}

When nothing matches, the result is { "status": "not_found" }. See Response fields in Read memories.

Search memories

The search_memories tool returns ranked memories for a question. Takes the scope arguments.

Argument	Type	Required	Description
`query`	string	Yes	1 to 1,000 characters.
`limit`	integer	No	3 by default. Clamped to 1 to 10.
`occurred_after`	date-time	No	Only memories from this time on.
`occurred_before`	date-time	No	Only memories from before this time.

{
  "data": [
    {
      "status": "active",
      "memory_id": "mem_01K6Y3V9QF2W8H4N7C5X0RZB1D",
      "ranked_score": 0.9204
    }
  ],
  "has_more": false
}

Each item is a full memory, shortened here. Search returns its best candidates ranked by ranked_score, so your application can apply its own cut-off.

Recall by ID

The recall_by_id tool returns one memory by ID.

Argument	Type	Required	Description
`memory_id`	string	Yes	Up to 128 characters.

The result is the memory, without ranked_score, or { "status": "not_found" } when the memory is missing, forgotten or still forming.

Inspect memory

The inspect_memory tool returns one memory with its versions, newest first, how Alvia classified each one and why, and its relationships to other active memories. An agent uses it to explain how a memory changed or what it relates to; recall_by_id is enough to read a memory.

Argument	Type	Required	Description
`memory_id`	string	Yes	Up to 128 characters.

{
  "status": "active",
  "memory": {
    "memory_id": "mem_01K6R8QJ2N4P6S8T0V2X4Z6B8D",
    "head_version": 2,
    "versions": [
      { "version": 2, "outcome": "supersession" },
      { "version": 1, "outcome": "novel" }
    ],
    "relationships": [
      {
        "target_id": "mem_01K6S4H7MC3R5T7V9X1Z3B5D7F",
        "edge_type": "related"
      }
    ]
  }
}

memory holds the same fields as GET /v1/memories/{memory_id}/inspect, shortened here. See Inspect a memory in Read memories. When the memory is missing, forgotten or still forming, the result is { "status": "not_found" }.

List memories

The list_memories tool lists active memories, newest first. Takes the scope arguments.

Argument	Type	Required	Description
`skip`	integer	No	Memories to skip. 0 by default, at most 10,000.
`take`	integer	No	Memories to return. 20 by default, at most 20.

{
  "data": [
    { "status": "active", "memory_id": "mem_01K6Y3V9QF2W8H4N7C5X0RZB1D" }
  ],
  "has_more": true
}

Each item is a full memory, shortened here. For the next page, set skip to this call’s skip plus the number of memories returned. To reach memories past 10,000, use search_memories.

Forget memory

The forget_memory tool forgets a memory. See Forget a memory in Manage memories.

Argument	Type	Required	Description
`memory_id`	string	Yes	Up to 128 characters.

{
  "memory_id": "mem_01K6Y3V9QF2W8H4N7C5X0RZB1D",
  "status": "success",
  "message": "Memory deactivated."
}

Status	Meaning
`success`	The memory is forgotten.
`accepted`	The memory is forgotten; Alvia finishes removing it from search in the background.
`not_found`	There is no such memory.

Give memory feedback

The give_memory_feedback tool records feedback on a memory. See Give feedback in Manage memories.

Argument	Type	Required	Description
`memory_id`	string	Yes	Up to 128 characters.
`is_favorited`	boolean	Yes	`true` raises the memory’s rank.
`sentiment`	string	Yes	`positive`, `negative` or `neutral`.

{
  "memory_id": "mem_01K6Y3V9QF2W8H4N7C5X0RZB1D",
  "status": "success",
  "message": "Feedback recorded."
}

When the memory is missing or forgotten, status is not_found.

Resource

The server offers one resource template, alvia://memory/{memory_id}. Reading it returns the same result as recall_by_id, as application/json. The template is listed by resources/templates/list.

Tool hints

Tool	Read-only	Destructive	Idempotent
`remember`	No	No	Yes
`context`	Yes	No	Yes
`recall`	Yes	No	Yes
`search_memories`	Yes	No	Yes
`recall_by_id`	Yes	No	Yes
`inspect_memory`	Yes	No	Yes
`list_memories`	Yes	No	Yes
`forget_memory`	No	Yes	Yes
`give_memory_feedback`	No	No	Yes

Retry remember only when the call failed: a network error, a service failure or a rate limit (after the wait the error gives). A queued result means Alvia accepted the content, so do not send it again. When you retry, send the same content and occurred_at. Each accepted call uses writes. See Retries in Store memories.

Every tool works only on the memories in the key’s project: openWorldHint is false on every tool.

Errors

Argument mistakes, rate limits, used-up allowances and failures return tool errors. See Errors in MCP tools in Errors.