setup

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:

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