Skip to content

Connect a coding agent

This guide shows how to give your coding agent context that stays true from one session to the next. You install Alvia’s plugin for Claude Code, Codex, Cursor, OpenClaw or Hermes, or add Alvia’s remote MCP server to any other MCP client, then tell the agent something in one session and ask about it in a new one. MCP, the Model Context Protocol, lets an agent call tools that a service provides.

This connection gives your own agent context while you work. To add Alvia to the application you are building, start with Quickstart or Add memory to an LLM app. For how Alvia relates to CLAUDE.md, AGENTS.md and Claude Code’s auto memory, see Alvia compared with other approaches.

Install the plugin

Section titled “Install the plugin”

The plugin is the recommended way to connect. It adds Alvia’s memory tools, tells the agent to ask Alvia for team decisions before it searches or guesses and saves each finished conversation to Alvia. The plugins are in the public alvia-ai/integrations repository.

Terminal
claude plugin marketplace add alvia-ai/integrations
claude plugin install alvia-memory@alvia-integrations \
  --config api_key="$ALVIA_API_KEY"

In Claude Code, /plugin runs the same steps and asks for the key.

Connect with MCP only

Section titled “Connect with MCP only”

Without a plugin, add Alvia’s remote MCP server. The agent gets the same tools, but it saves nothing on its own: it remembers what you ask it to.

To make Alvia available in every Claude Code project, run:

Terminal
claude mcp add \
  --scope user \
  --transport http \
  alvia https://api.alvia.ai/mcp \
  --header "Authorization: Bearer $ALVIA_API_KEY"

To add it to one project only, with that project’s own key, run the command from the project’s root directory with --scope local instead of --scope user. Claude Code stores the setting on your computer, not in the project’s files.

Test it in two sessions

Section titled “Test it in two sessions”

  1. Ask the agent: “Remember that the Atlas service now uses PostgreSQL 17.”

    The agent calls the remember tool. Most clients show tool calls as they happen.

  2. Wait for formation to finish, in less than a minute.

  3. End the session and start a new one, so the agent starts fresh. Ask: “Which database does the Atlas service use? Check Alvia.”

    The agent calls the context or recall tool and answers from the result.

To see what the agent stored, open the project’s Memories in the dashboard.

If the client reports an authentication error, check the key and the header name. If it lists no tools, check that the URL ends in /mcp.

Tell the agent when to use Alvia

Section titled “Tell the agent when to use Alvia”

The plugin already tells the agent when to ask Alvia. Without a plugin, an agent calls a tool when the request suggests it. To have it check Alvia and record decisions without being asked, say so in the instructions file it reads at the start of every session, such as CLAUDE.md or AGENTS.md:

AGENTS.md
Before you change the architecture, ask Alvia's context tool for the
current decision. When we make a decision, remember it with Alvia,
with the reason.

The instructions file holds the rules you write and review; Alvia holds what the team learns and decides as work goes on, and returns the current version when a decision changes. See Alvia for coding agents.

Set the memory policy before the agent writes

Section titled “Set the memory policy before the agent writes”

The agent writes to the project selected by its key, so it uses that project’s keyword and meaning exclusions. Configure Memory policy in the dashboard before connecting an agent to real conversations. An agent instruction such as “do not remember health information” shapes the interaction; the project policy controls what becomes memory.

For a team agent, exclude credentials and customer payloads while retaining design decisions. For a personal assistant, exclude sensitive disclosures while retaining useful preferences. Test the policy with synthetic tool writes and inspect the formed memories. See Filter memories.

Server settings

Section titled “Server settings”
Setting Value
URL https://api.alvia.ai/mcp
Transport Streamable HTTP
Authentication Authorization: Bearer <API_KEY>

Authenticate with a project API key.

Tools

Section titled “Tools”
Tool What the agent does with it
remember Store a fact or a passage.
context Get resolved context for a question.
recall Get the single best memory for a question.
search_memories Get ranked memories, 20 by default and up to 50.
recall_by_id Get one memory by ID.
inspect_memory See how a memory changed and what it relates to.
list_memories List memories, newest first.
forget_memory Forget a memory.
give_memory_feedback Mark a memory as useful, wrong or a favorite.

See Alvia MCP server tools for every argument and result. Import conversations over REST, as in Import conversations.

Scope

Section titled “Scope”

Every tool except recall_by_id, inspect_memory, forget_memory and give_memory_feedback takes organization_id, user_id, application_id, agent_id and team_id as separate arguments. The tool descriptions tell the agent to pass the IDs it has and to use the same IDs every time. To keep each agent’s memories apart, give the agent its ID in its instructions:

Agent instructions
Use agent_id "release-bot" on every Alvia tool call.

The Claude Code, Codex and Cursor plugins use the repository as the scope by default: application_id is owner/repo from the origin remote, so every clone of the repository shares the same memories. Set ALVIA_APPLICATION_ID or another ALVIA_*_ID variable to choose your own. See Projects and scope.

Cost

Section titled “Cost”

MCP calls share your account’s rate limits and monthly allowances with REST calls. Each remember call uses writes as POST /v1/memories does: one, plus one for each fact formed from the content. Each read tool call that completes uses reads as its REST call does, whatever it returns: five for context, three for inspect_memory and one for each other read tool. forget_memory and give_memory_feedback use none. A plugin saves a conversation as an import: one write for each chunk, plus one for each fact formed from it. See Limits and allowances and Rate limits.

Retries

Section titled “Retries”

The agent decides whether to call a tool again. Call again only after a tool error: a rate-limit error says how many seconds to wait. A successful remember call means Alvia accepted the content, so it does not need another. Each accepted call uses writes. Calls resume when the monthly allowance resets.

Errors

Section titled “Errors”

Tools report a wrong argument, a rate limit, a used-up allowance, the stored-memory limit or an unexpected failure as a tool error with a message, not a status code. forget_memory and give_memory_feedback report a missing memory as "status": "not_found" in their result. See Errors in MCP tools for each message.

Section titled “Related pages”