setup

name	setup
description	Install Memoria and configure MCP for AI tools (Kiro, Cursor, Claude Code, Codex, Gemini CLI). Decision tree for Cloud vs self-hosted mode, database, embedding provider. Use when helping users set up Memoria.

Decision Tree

Follow these steps in order. Steps marked "Self-Hosted only" can be skipped for Memoria Cloud users.

Step 1: Memoria Cloud or Self-Hosted?

Ask: "Use Memoria Cloud, or run your own instance?"

• Memoria Cloud (recommended) → sign up at thememoria.ai, get API URL + token, then proceed to Step 2
• Self-hosted → proceed to Step 2

Step 2: Which AI tool?

Ask: "Which AI tool are you using — Kiro, Cursor, Claude Code, Codex, or Gemini CLI?"

The --tool flag value and config files generated per tool:

Tool	--tool value	Config files
Kiro	kiro	.kiro/settings/mcp.json + .kiro/steering/memory.md
Cursor	cursor	.cursor/mcp.json + .cursor/rules/memory.mdc
Claude Code	claude	.mcp.json + CLAUDE.md
Codex	codex	~/.codex/config.toml + AGENTS.md
Gemini CLI	gemini	.gemini/settings.json + GEMINI.md

Step 3: Database (Self-Hosted only)

Skip this step if user chose Memoria Cloud in Step 1.

Ask: "Do you have a MatrixOne database running?"

• Already have one → get connection URL (format: mysql+pymysql://<user>:<pass>@<host>:<port>/<db>)
• No → run docker compose up -d in the Memoria repo root (wait 30-60s for first start)

Step 4: Embedding provider (Self-Hosted only)

Skip this step if user chose Memoria Cloud in Step 1.

⚠️ Hard to reverse. Embedding dimension is locked into schema on first startup.

Ask: "Do you have an OpenAI-compatible embedding endpoint?"

• Yes → collect: base URL, API key, model, dimension
• No → suggest SiliconFlow (free tier) or Ollama. Local embedding requires --features local-embedding build.

Step 5: Install Memoria CLI

The memoria binary is required for all modes — it serves as the MCP bridge between the AI tool and the Memoria server.

One-line install (recommended):

curl -sSL https://raw.githubusercontent.com/matrixorigin/Memoria/main/scripts/install.sh | bash

Or download manually from GitHub Releases.

Platform-specific manual install:

# Linux x86_64
curl -LO https://github.com/matrixorigin/Memoria/releases/latest/download/memoria-x86_64-unknown-linux-musl.tar.gz
tar xzf memoria-x86_64-unknown-linux-musl.tar.gz && sudo mv memoria /usr/local/bin/

# macOS Apple Silicon
curl -LO https://github.com/matrixorigin/Memoria/releases/latest/download/memoria-aarch64-apple-darwin.tar.gz
tar xzf memoria-aarch64-apple-darwin.tar.gz && sudo mv memoria /usr/local/bin/

# From source (required for local embedding)
cd Memoria/memoria && cargo build --release -p memoria-cli
# With local embedding: cargo build --release -p memoria-cli --features local-embedding
sudo cp target/release/memoria /usr/local/bin/

Verify: memoria --version

Step 6: Configure

Memoria Cloud (Remote Mode)

Sign up at thememoria.ai — after login you will receive the API URL and token.

cd <user-project>
memoria init --tool <tool> --api-url '<API URL from thememoria.ai>' --token '<your token>'

Replace <tool> with the value from Step 2 (e.g., kiro, cursor, claude, codex, gemini).

Self-Hosted: Local Docker

docker compose up -d                    # Start MatrixOne
docker ps --filter name=matrixone       # Verify (wait 30-60s)
cd <user-project>
memoria init --tool <tool>              # + embedding flags below

Self-Hosted: Existing DB

cd <user-project>
memoria init --tool <tool> --db-url 'mysql+pymysql://<user>:<pass>@<host>:<port>/<db>'

Embedding Flags (Self-Hosted only)

# Local (default, no flags)
memoria init --tool <tool>

# OpenAI-compatible
memoria init --tool <tool> \
  --embedding-provider openai \
  --embedding-base-url https://api.siliconflow.cn/v1 \
  --embedding-api-key sk-... \
  --embedding-model BAAI/bge-m3 \
  --embedding-dim 1024

Step 7: Verify

After running memoria init, tell user to:

1. Restart their AI tool
2. Ask the AI: "Do you have memory tools available?"
3. Or run: memoria status

Expected: memory_retrieve("test") → "No relevant memories found".

Post-Setup

memoria rules --force   # After upgrading Memoria binary, re-sync steering rules

MCP Server Modes (Reference)

These are the underlying commands that memoria init configures. Users normally don't need to run them directly.

# Embedded mode (direct DB connection, self-hosted)
memoria mcp --db-url "mysql+pymysql://root:111@localhost:6001/memoria" --user alice

# Remote mode (proxy to Memoria API server, Cloud or self-hosted API)
memoria mcp --api-url "<API URL>" --token "<token>"

# SSE transport (alternative to default stdio)
memoria mcp --transport sse

Troubleshooting

Problem	Fix
MatrixOne won't start	docker logs memoria-matrixone
Port 6001 in use	Change MO_PORT in .env
Can't connect to DB	Wait 30-60s on first start
Docker permission denied	sudo usermod -aG docker $USER && newgrp docker
Docker not available	Use Memoria Cloud instead (no Docker needed)
First query slow	Normal with local embedding (~3-5s). Use openai provider for faster response
local-embedding not compiled	Use OpenAI-compatible service, or build from source with --features local-embedding
AI tool doesn't see memory tools	1. Run which memoria to verify CLI installed 2. Restart AI tool 3. Test MCP server directly