Docs

Connect an agent to Memoria.

Everything you need to give an agent long-term memory: getting a key, connecting over MCP or Python, the five memory tools, and the rules for sharing, signatures and limits.

Try it now

Connect any MCP app with these public demo keys to see Memoria working before you have your own.

# Endpoint
https://www.memoriaagent.site/mcp
# Demo agent A
mem_7bc3decac803_k497dv56o8MU3H8HRIstwfXHlvK9Fwd_WnZM_uvLB74
# Demo agent B
mem_aeab1c37b20d_YS_FoHyUoSrtGNijAXITarN-NFOHM7Z6z9_2i3T1eQ8

Agent A shared one memory with agent B and kept one private. Search with each key to see that B finds the shared one but never A's private one.

Both demo keys are read-only: they can only use find_memory, and each returns 2 of the 3 signed sample memories.

Getting access

Memoria is in early access. Join the waitlist and we'll email you when developer access opens. You then get two things:

  • Your server address, the URL your agents connect to. The MCP endpoint is that address followed by /mcp.
  • An API key that starts with mem_. Each key belongs to one agent in your account. It's shown once, so keep it somewhere safe. We only store a hash of it and can't show it again.

An account can have up to 10 agents, each with its own key. Ask for a new key for every agent you want to tell apart: the key decides which agent a memory is saved as.

Connect an agent

Every request sends the key as a header: Authorization: Bearer mem_.... The examples below read the address and key from the environment variables MEMORIA_URL and MEMORIA_API_KEY.

Claude Code

claude mcp add --transport http \
  memoria "$MEMORIA_URL/mcp" \
  --header \
  "Authorization: Bearer $MEMORIA_API_KEY"

Then ask in any session, for example "Check Memoria for what we know about Acme" or "Save this decision to Memoria".

Other MCP apps

Apps that connect to remote MCP servers over HTTP, such as Cursor and VS Code, take a few lines in their MCP settings. Put your real address and key in place of the values in capitals.

{
  "mcpServers": {
    "memoria": {
      "url": "https://YOUR_MEMORIA_ADDRESS/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Some apps use a slightly different settings shape; check your app's guide for remote MCP servers with custom headers.

Your own Python agent

Any MCP client works. With the official mcp Python package, version 2.3 or later:

# pip install "mcp>=2.3"
import asyncio, os
import httpx2
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client

async def main():
    url = os.environ["MEMORIA_URL"] + "/mcp"
    auth = {"Authorization": "Bearer " + os.environ["MEMORIA_API_KEY"]}
    async with httpx2.AsyncClient(headers=auth, timeout=httpx2.Timeout(30, read=300)) as http:
        async with streamable_http_client(url, http_client=http) as (read, write):
            async with ClientSession(read, write) as memoria:
                await memoria.initialize()
                await memoria.call_tool("save_memory", {
                    "note": "Acme's contract renews on March 1.",
                    "reason": "From the signed renewal email.",
                    "topic": "customers/acme",
                    "confidence": "high",
                })
                found = await memoria.call_tool("find_memory", {"query": "When does Acme renew?"})
                print(found.content)

asyncio.run(main())

The memory tools

Memoria gives every connected agent five tools. Agents only ever see memories they are allowed to read.

ToolWhat it doesArguments
save_memorySaves a note or decision with the reason behind it.note, reason, topic, optional confidence (low, medium, high; default medium), visibility (private or shared; default private), shared_with
find_memorySearches by question or keywords. Best matches first.query, optional topic, saved_by, limit (1 to 20; default 5)
update_memoryReplaces a memory's note. The old version is kept in its history.memory_id, new_note, reason, optional confidence, topic
share_memoryChanges who can read a memory. Only the writer can do this.memory_id, visibility, shared_with (the full new list)
delete_memoryDeletes a memory and its history for good. Only the writer can do this.memory_id

Memory IDs look like mem-1a2b3c4d and come back from save_memory and find_memory. If a memory is only out of date, update it rather than deleting it, so its history is kept.

Sharing

Every memory is one of two kinds:

  • Private (the default): only the agent that wrote it can find or update it.
  • Shared: the writer plus the agent IDs in shared_with, for example ["sales"]. Agents it's shared with can read and update it, but can't delete it or change who sees it.

Sharing only reaches agents in your own account. Each account's memories are kept apart, and your searches never look at anyone else's.

Signatures

Every saved or updated memory is signed with an Ed25519 key that belongs to the agent that wrote that version. The signature covers the memory's content and labels: its ID, account, topic, confidence, note, reason, writer and time. It doesn't cover sharing, so changing who can read a memory doesn't break it.

find_memory checks every signature again and reports it, for example verified: signed by researcher or NOT verified: the memory was changed after it was signed.

What a signature proves: that an agent holding that key saved the memory and that it hasn't changed since. Memoria signs on the agent's behalf after the agent proves who it is with its API key.

Search and indexing

Saving, updating and deleting answer straight away. Indexing for search by meaning happens afterwards in the background, and can take a few minutes when it's busy. While a memory waits it shows processing: true, and find_memory still finds it by the words in your question.

Indexing uses Google Gemini to read each memory. See the Privacy Policy for what that means for your data.

Limits

Early access accounts start with these limits. Going over a per-minute limit returns 429 Too Many Requests with a Retry-After time; other limits return a clear message.

WhatLimit
Requests per minute, per agent60
Requests per minute, per account120
Saves and updates per day, per account200
Memories kept, per account2,000
Agents per account10
Size of one request64 KB
Note / reason / topic / question length4,000 / 2,000 / 100 / 1,000 characters
Wrong API keys from one address10, then a 10 minute lock-out

Good practice

  • Write notes that make sense on their own, and say why in reason. Future agents won't have today's context.
  • Use short, consistent topics such as customers/acme or project/website, so searches can filter by them.
  • Never save passwords, API keys or other secrets in a memory.
  • Keep each agent's key in that agent's environment, not in your code or your repository.