CLI

The memoria CLI is a single binary that handles install + auth + MCP config in one step. Run it once per machine (or once per cloud environment) and every Claude Code session can call Memoria's tools — and already understands what brains, episodes, entities, edges, and playbooks are, because memoria init also installs a Claude Code skill that teaches the agent.

It's open source at github.com/premex-ab/memoria-cli.

Prefer the browser OAuth flow on your laptop? You don't need the CLI for that — see MCP server. The CLI shines for API-key and cloud setups, like Claude Code on the web (see below).

Install

curl -fsSL https://api.memoria.premex.se/install.sh | sh

This downloads the right binary for your OS and architecture (macOS and Linux, arm64 and amd64) to ~/.local/bin/memoria. Make sure ~/.local/bin is on your PATH.

Connect

Mint a mem_live_* key in the dashboard under Brains → your brain → Keys, then:

memoria init mem_live_…

init validates the key, prints which brain it's bound to, stores the token, writes the memoria MCP entry into ~/.claude.json, and installs the skill into ~/.claude/skills/memoria/. Open a Claude Code session and try recall("hello world") to confirm.

The token never lands in ~/.claude.json. The MCP entry references a helper command (memoria headers) that resolves the Authorization header at connection time:

{
  "mcpServers": {
    "memoria": {
      "type": "http",
      "url": "https://api.memoria.premex.se/mcp",
      "headersHelper": "memoria headers"
    }
  }
}

init stores the token in your OS keychain on macOS, or in ~/.config/memoria/credentials (mode 600) otherwise. When a key rotates, re-run memoria init <new-key> — everything downstream keeps working.

Claude Code on the web

Claude Code on the web runs each session in an isolated, ephemeral cloud container — no persistent keychain, no browser for an interactive OAuth flow. The CLI's env-var mode fits perfectly: provide the API key through the environment's configuration, and a short setup script installs the CLI, wires the MCP server, and installs the skill on every fresh container. No committed config file, no secret in your repo.

1. Add your API key to the environment's variables. In the environment configuration, set:

MEMORIA_API_KEY=mem_live_…

Bind the key to the brain you want web sessions to read and write — typically a per-project brain.

2. Set the environment's setup script to:

#!/bin/bash
set -e
curl -fsSL https://api.memoria.premex.se/install.sh | sh
memoria init "$MEMORIA_API_KEY"

On each fresh container this installs the binary, then runs init, which sees MEMORIA_API_KEY in the environment and enters env-var mode: it validates the key, writes the MCP entry, and installs the skill — but never writes the token to disk. memoria headers reads the key straight from the environment at connect time.

3. Allow the right hosts in the network policy. Web environments enforce an outbound network policy. The setup and runtime need to reach:

• github.com and objects.githubusercontent.com — the installer downloads the binary from GitHub Releases.
• api.memoria.premex.se — the install redirect, key validation, and the /mcp endpoint.

Pick a policy that permits those, or allowlist them — otherwise the setup script can't fetch the binary.

That's it. The first session comes up with the Memoria tools available and the memoria skill auto-loaded, so the agent already knows the mental model, the bi-temporal "two clocks", brain isolation, and what each tool costs.

Command reference

Command	What it does
memoria init <token>	Validate the key, store it, write the MCP entry, install the skill.
memoria init --token-env MEMORIA_API_KEY	Same, reading the token from an env var — env-var mode, for cloud and CI.
memoria headers	Internal. Resolves the Authorization header for the MCP server at connect time (env → keychain → file).
memoria status	Show the bound brain, where the token is stored, and whether the MCP entry and skill are in place.
memoria update	Self-update to the latest release.
memoria mcp print	Print the MCP JSON entry without writing anything.
memoria --version / --help	Standard.

Troubleshooting

• claude mcp list doesn't show memoria. Run memoria status to confirm the MCP entry is present. Current Claude Code versions ignore ~/.claude/settings.json for MCP config — user-scope servers live in ~/.claude.json, which memoria init writes for you.
• Tools fail to connect in a web session. Almost always the network policy or a missing/mistyped MEMORIA_API_KEY. Run memoria status in the session — it reports whether the token resolved and which brain it's bound to.
• init exits with a 401. The key is invalid, revoked, or for a brain that no longer exists. Mint a fresh one from the dashboard.

See also

• MCP server — the tool catalog and the browser OAuth flow.
• Brains — how keys and tokens bind to an isolated workspace.
• Quickstart — store and recall your first memory.