Skip to content

cli.md

Latest commit

 

History

History
236 lines (161 loc) · 8.22 KB

cli.md

File metadata and controls

236 lines (161 loc) · 8.22 KB
Raw

memoria CLI reference

memoria is the command-line interface for Memoria — bi-temporal AI agent memory served over MCP. It handles install + auth + MCP config in one shot, and deposits a Claude Code skill so every session in a configured project automatically reads Memoria's mental model.

Install

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

The installer:

  1. Resolves the latest release from GitHub.
  2. Downloads the binary for your OS and architecture (darwin/arm64, darwin/amd64, linux/arm64, linux/amd64).
  3. Writes it to ~/.local/bin/memoria and marks it executable.

After install, make sure ~/.local/bin is on your PATH:

# Add to ~/.zshrc or ~/.bashrc if it's not already there
export PATH="$HOME/.local/bin:$PATH"

Verify:

memoria --version

Commands

memoria init <token>

Connects a Memoria brain to your Claude Code sessions.

memoria init mem_live_<your-key>

What it does:

  1. Validates the token by calling GET /v1/whoami against the Memoria API.
  2. Prints the bound tenant and brain name.
  3. Stores the token securely (see Token resolution order below).
  4. Writes the mcpServers.memoria entry into ~/.claude.json using the headersHelper mechanism — the token is never stored in ~/.claude.json in plaintext.
  5. Deposits the memoria skill at ~/.claude/skills/memoria/SKILL.md.

Flags:

Flag Default Description
--api-url URL https://api.memoria.premex.se Override the API base URL (useful for self-hosted or staging)

Cloud / CI environment setup:

When MEMORIA_API_KEY is set in the environment, memoria init skips the keychain write and records the install as "env-var mode"; memoria headers then reads the key at MCP connection time. This is the pattern for CI and cloud dev environments where environment variables are available to setup/bootstrap scripts — GitHub Actions, Codespaces, devcontainers, etc.:

# Setup script
curl -fsSL https://api.memoria.premex.se/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"   # the installer writes to ~/.local/bin
memoria init "$MEMORIA_API_KEY"

Claude Code on the web is different. Variables you set in the environment's Environment variables panel are not available to the Setup script — Claude Code injects them only once the session is running. So $MEMORIA_API_KEY is empty during setup, and memoria init "$MEMORIA_API_KEY" fails with token rejected by server. Use one of these instead:

  • Declarative MCP (recommended — no CLI needed). Commit a .mcp.json to your repo. Claude Code expands ${MEMORIA_API_KEY} from the panel at MCP connection time (which is runtime, where the variable exists):
{
  "mcpServers": {
    "memoria": {
      "type": "http",
      "url": "https://api.memoria.premex.se/mcp",
      "headers": { "Authorization": "Bearer ${MEMORIA_API_KEY}" }
    }
  }
}
  • Inline key in the setup script. Pass the key directly to memoria init — don't reference $MEMORIA_API_KEY, which isn't set yet:
curl -fsSL https://api.memoria.premex.se/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
memoria init "mem_live_…"

Either way the key lives in your environment config, which is visible to anyone with access to that environment — use a dedicated, revocable key.

Pin a version (optional) for reproducible installs — and to skip the GitHub release lookup entirely, which sidesteps GitHub's unauthenticated API rate limit on shared CI/sandbox egress IPs. Set MEMORIA_VERSION:

curl -fsSL https://api.memoria.premex.se/install.sh | MEMORIA_VERSION=cli/v0.1.0 sh

memoria headers

Resolves the active API token and prints an HTTP Authorization header as JSON. This command is invoked automatically by Claude Code's headersHelper mechanism at MCP connection time — you do not need to run it manually.

memoria headers

Output:

{"Authorization":"Bearer mem_live_..."}

Resolution order: env var → macOS keychain → credentials file. See Token resolution order below.

Note: This command must complete in under 10 seconds (Claude Code's headersHelper timeout). If the keychain is locked (e.g. a non-interactive shell on macOS), the command exits non-zero with a clear error message so the session log shows the cause.

memoria status

Shows the current Memoria configuration and connection state.

memoria status

Output includes:

  • Which brain the configured token belongs to (one round-trip to /v1/whoami)
  • Where the token is stored (keychain / env var / credentials file)
  • When the token was last rotated (from ~/.config/memoria/state.json)
  • Whether ~/.claude.json has the mcpServers.memoria entry
  • Whether ~/.claude/skills/memoria/SKILL.md exists and matches the binary's embedded version
  • CLI version and last update-check time

Flags:

Flag Default Description
--api-url URL https://api.memoria.premex.se Override the API base URL

memoria update

Self-updates the CLI to the latest release.

memoria update

Resolves the latest GitHub Release, downloads the binary for the current OS and architecture, and atomically replaces ~/.local/bin/memoria via a temp file + rename. The update is refused if the downloaded version is older than the current one.

Flags:

Flag Default Description
--check-only false Print whether an update is available without downloading
--source URL GitHub Releases API Override the releases endpoint (for testing or mirrors)

memoria --version / memoria -v

Prints the CLI version.

memoria --version
# memoria version v0.1.0

Token resolution order

memoria headers (and by extension every Claude Code session using the MCP server) resolves the token in this order:

  1. $MEMORIA_API_KEY environment variable — if set, used immediately. No keychain or file access. Intended for CI, cloud environments, and containerized agents.
  2. macOS keychain (darwin only) — security find-generic-password -s memoria.premex.se -a $USER -w. memoria init writes here on macOS when $MEMORIA_API_KEY is not set.
  3. ~/.config/memoria/credentials file — plaintext fallback for Linux and other environments without a system keychain. Written with chmod 600. memoria init warns when this fallback is used.
  4. → Error. All three sources failed. Run memoria init <token> or set $MEMORIA_API_KEY.

~/.config/memoria/state.json

A JSON file written by memoria init and read by memoria status. Records:

{
  "tenantId": "tenant-abc",
  "brainId": "default",
  "brainName": "My brain",
  "installedAt": "2026-05-28T10:00:00Z",
  "lastTokenRotation": "2026-05-28T10:00:00Z",
  "lastUpdateCheck": "2026-05-28T10:00:00Z",
  "tokenSource": "keychain",
  "cliVersion": "v0.1.0"
}

Do not hand-edit this file. memoria status reads it for display; memoria init overwrites it. If it becomes corrupted, delete it and re-run memoria init.

The headersHelper mechanism

Claude Code's ~/.claude.json supports a headersHelper field on MCP server entries. When set, Claude Code runs the specified command at MCP connection time and merges the resulting JSON object into the request headers. This means the actual token never appears in ~/.claude.json — it is resolved at connection time from whatever secure storage the CLI uses.

The entry written by memoria init:

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

If memoria headers exits non-zero (e.g. keychain locked, token missing), Claude Code surfaces the error in the session log. The fix is always memoria init <token> or ensuring $MEMORIA_API_KEY is set.

See also