Start

Quickstart

Memoria is a hosted memory layer. Agents typically talk to it through a stateless MCP adapter on your machine. Scripts and apps can use the same HTTP API via the Python or Node SDK, or the memoria-cloud CLI. Set MEMORY_API_URL to https://memoria-api-jw5g.onrender.com. Create a key in the dashboard and put it in env as MEMORY_API_KEY.

The MCP adapter tells the agent to emit conversation turns. Use remember when a fact must persist immediately, and recall to search.

NOTE

Put the key in MCP environment variables. Do not paste it into prompts, AGENTS.md, or chat.

Prerequisites

You need uv so the harness can spawn uvx. uv can fetch Python 3.12+ on first run. After installing, restart the terminal and the harness so uvx is on PATH. Confirm with uvx --version.

macOS / Linux:

bash

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

API key

Sign in to the dashboard with Google.
Open Keys and create a key. Copy the mem_... value once.
In MCP env set MEMORY_API_URL to https://memoria-api-jw5g.onrender.com and paste the key as MEMORY_API_KEY. Replace mem_... — do not leave the placeholder. Do not set MEMORY_SESSION_ID.

The first uvx start clones the MCP adapter from GitHub. That can take a minute. Later starts are faster. Render may cold-start the API after idle, so the first remember or recall can take a few seconds.

Cursor / Claude Code

Cursor: ~/.cursor/mcp.json or project .cursor/mcp.json. Claude Code: MCP settings / .mcp.json. The adapter runs locally. Env must include MEMORY_API_URL = https://memoria-api-jw5g.onrender.com and MEMORY_API_KEY.

json

{
  "mcpServers": {
    "memoria": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/JayTheCoder77/memoria.git#subdirectory=apps/mcp-server",
        "memoria-mcp"
      ],
      "env": {
        "MEMORY_API_URL": "https://memoria-api-jw5g.onrender.com",
        "MEMORY_API_KEY": "mem_..."
      }
    }
  }
}

OpenCode

OpenCode does not use mcpServers. Put this in project opencode.json / opencode.jsonc, or globally in ~/.config/opencode/opencode.json. Command is a single array. Env is environment with MEMORY_API_URL = https://memoria-api-jw5g.onrender.com and MEMORY_API_KEY. Timeout is 60s so the first uvx fetch is not killed.

json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "memoria": {
      "type": "local",
      "command": [
        "uvx",
        "--from",
        "git+https://github.com/JayTheCoder77/memoria.git#subdirectory=apps/mcp-server",
        "memoria-mcp"
      ],
      "enabled": true,
      "timeout": 60000,
      "environment": {
        "MEMORY_API_URL": "https://memoria-api-jw5g.onrender.com",
        "MEMORY_API_KEY": "mem_..."
      }
    }
  }
}

Org vs session

Tenancy is the org on your API key. Session is a label on writes, not a second tenant. Do not put a session id in MCP JSON. Clients do not update that file when you start a new chat.

Scope	How tools use it
Org-wide	Implied by `MEMORY_API_KEY`. Default `recall` searches every memory in that org (any session). `update` and `forget` target one row by `memory_id` inside the org. Memories never cross orgs.
Session-wide	`remember` and `emit` tag writes with an auto session id for this harness process. `emit(session_end)` flushes extraction and starts a new id. Pass `session_id` on `recall` only when you want that conversation, not the whole org. Optional `session_id` on write pins a label; omit it otherwise.

Tools

Five tools. Org comes from the API key. Do not set MEMORY_SESSION_ID in MCP JSON. Writes get an auto session id for this harness process; emit(session_end) flushes extraction and starts a new one. recall searches the whole org unless you pass session_id. Tools never take a key.

Tool	Description
remember	Immediate save of the caller text (no rewrite). Deduped. Stores the canonical memory, then fills KV and graph. Use when you or the agent are sure a fact must persist now. `memory_type` is episodic, semantic, or procedural.
emit	Queue only. Call after user turns; do not wait for the user to ask. Types: `message`, `tool_call`, `diff`, `session_end`. Noisy reads/greps are skipped. Not every event becomes a memory. The worker extracts later. Pending in the Event Buffer until 10 events or `session_end` is normal. `session_end` flushes the batch and rotates the auto session id.
recall	Sync search across vector, KV, and graph, fused by relevance, importance, and recency. Query with `q`. Org-wide unless you pass `session_id`. Optional `as_of` (ISO datetime) reads historical graph edges.
update	Patch an existing memory by `memory_id` (content, importance, or type). New content is re-embedded. Does not re-run LLM extraction or rewrite KV/graph.
forget	Delete one memory by `memory_id`. KV facts for that row are removed. Graph edges stay; their `memory_id` is cleared.

Writes and fallbacks

Paste keys in dashboard Settings. Extraction tries OpenRouter (your model), then Groq (fixed openai/gpt-oss-20b), then regex/heuristic. Missing Groq skips Groq. Rate limits and HTTP errors still succeed; they fall through. LLM/Groq cannot fail remember.

remember enriches KV/graph on that request. emit only queues; the same cascade runs in the worker. Recall query parsing uses OpenRouter if configured, else regex — not the Groq cascade.

SDK and CLI

For Python or Node outside a harness, skip MCP. Same key, same API. pip install memoria-cloud-sdk / npm install memoria-cloud-sdk, or pip install memoria-cloud-cli. See Python and Node SDKs and the CLI.