@mnemo-ai/cli

AI pointer: Operations CLI — mnemo recall, mnemo remember, mnemo forget, mnemo status, mnemo config. Wraps client-ts.

Depends on: @mnemo-ai/client-ts (no framework deps — native fetch only)

Exposes: mnemo CLI binary

Status: BETA — 20 commands wired + shell completion

See also: CLAUDE.md · docs/INDEX.md · docs/guides/CLI.md

The official command-line interface for Mnemosyne v3.

Overview

mnemo is a lightweight CLI for interacting with a running Mnemosyne server. It is intended for operators checking server health, developers storing and searching facts during local development, and shell scripts that need to integrate memory operations into automation pipelines.

Design philosophy — the binary uses native Node.js fetch only. There is no CLI framework (no commander, no yargs), no HTTP client library (no axios), and no external runtime dependencies. This keeps the install footprint minimal and startup time fast.

Installation

# pnpm (recommended)
pnpm add -g @mnemo-ai/cli

# npm
npm install -g @mnemo-ai/cli

Verify the install:

mnemo help

You should see the command reference printed to stdout.

Standalone Binary (no Node required)

You can build a self-contained binary that ships the runtime with the application code. Two strategies are supported: bun compile (preferred, smaller startup) and pkg (Node.js fallback).

Strategy 1 — bun compile (recommended)

Produces a single mnemo-standalone binary that embeds the Bun runtime (~58 MB on macOS arm64). No Node.js or npm needed on the target machine.

Prerequisites: Bun ≥ 1.1 installed on the build machine.

# From the repo root
pnpm --filter @mnemo-ai/cli build:standalone

# Or from packages/cli directly
bun build src/index.ts --compile --outfile dist/mnemo-standalone --target bun

Test it:

./packages/cli/dist/mnemo-standalone help
./packages/cli/dist/mnemo-standalone version

File size: ~58.6 MB (arm64 macOS).

Distribute:

# Install globally on the build machine
cp packages/cli/dist/mnemo-standalone /usr/local/bin/mnemo
chmod +x /usr/local/bin/mnemo

# Or copy to a server / CI artefact
scp packages/cli/dist/mnemo-standalone user@server:/usr/local/bin/mnemo

macOS code-signing note: The bun-compiled binary is an unsigned Mach-O executable. On macOS you may need to ad-hoc sign it before running it outside a terminal:

codesign --force --sign - dist/mnemo-standalone

Strategy 2 — pkg (Node.js fallback)

When Bun is not available on the build machine, use pkg to embed a Node 18 runtime. Requires only npx (ships with npm).

# From the repo root
pnpm --filter @mnemo-ai/cli build:binary

# Or manually:
bun build src/index.ts --outfile dist/index.cjs --target node --format cjs
npx pkg dist/index.cjs --target node18-macos-arm64 --output dist/mnemo-binary

Swap node18-macos-arm64 for other targets as needed:

• node18-linux-x64 — Linux x86-64
• node18-linux-arm64 — Linux arm64 (Raspberry Pi, AWS Graviton)
• node18-win-x64 — Windows x86-64

Test it:

./packages/cli/dist/mnemo-binary help

File size: ~44 MB (arm64 macOS).

Does dist/index.js work on another machine?

Yes, with caveats. The tsup output (dist/index.js) is a self-contained ESM bundle with no external npm dependencies — it only needs Node ≥ 20 on the target machine.

# Copy the single file and run it directly
scp packages/cli/dist/index.js user@server:/usr/local/lib/mnemo.js
chmod +x /usr/local/lib/mnemo.js

# Run (Node 20+ required)
node /usr/local/lib/mnemo.js help

For a zero-install distribution without Node, use the standalone binaries above.

Configuration

mnemo stores its configuration in ~/.mnemo/config.json. The directory and file are created automatically on first config set.

Config file format

{
  "url": "http://localhost:3939",
  "apiKey": "msk_..."
}

Environment variable override

Both values can be overridden at runtime without touching the config file:

| Variable | Overrides | Example | |-------------|-------------|----------------------------------| | MNEMO_URL | url | MNEMO_URL=http://prod.example.com | | MNEMO_KEY | apiKey | MNEMO_KEY=msk_yourkey |

Priority — environment variables take precedence over the config file. If neither is set, mnemo exits with code 1 and prints an actionable error message.

Initial setup

mnemo config set url http://localhost:3939
mnemo config set apiKey msk_yourkey

# Verify (apiKey is masked in output)
mnemo config get

Expected output:

{
  "url": "http://localhost:3939",
  "apiKey": "****...rkey"
}

Commands

mnemo recall <query>

Search memory using hybrid semantic + lexical search. Returns the top 10 hits ranked by relevance score (vector weight 0.7, lexical weight 0.3).

Syntax

mnemo recall <query>

Example

mnemo recall "user prefers TypeScript"

Output

id                                     │ score    │ statement
──────────────────────────────────────────┼──────────┼──────────────────────────────────────────────────
01j9abc123def456ghi789jkl012mno345pq   │ 0.9412   │ The user prefers TypeScript over Python
01j9abc789rst012uvw345xyz678abc901de   │ 0.8203   │ TypeScript generics allow type-safe reuse

Columns are fixed-width and aligned. The statement column truncates at 80 characters with an ellipsis (…) if the text is longer.

If no results are found:

No results found.

mnemo remember <text>

Store a new fact in memory. The text is stored as a single statement and immediately embedded.

Syntax

mnemo remember <text>

Example

mnemo remember "The user prefers TypeScript over Python"

Output

✓ Remembered: 01j9abc123def456ghi789jkl012mno345pq

The returned ID is a ULID that uniquely identifies this fact. Save it if you need to delete it later with mnemo forget.

mnemo forget <id>

Soft-delete a fact by its ID. The fact is removed from future search results.

Syntax

mnemo forget <id>

Example

mnemo forget 01j9abc123def456ghi789jkl012mno345pq

Output

✓ Forgotten: 01j9abc123def456ghi789jkl012mno345pq

Exits with code 1 if the ID does not exist or the server returns a non-2xx response.

mnemo status

Check server health. Hits /v1/health and pretty-prints the response with color-coded status values: green for ok/healthy, yellow for degraded, red for anything else.

Syntax

mnemo status

Example

mnemo status

Output (healthy)

{
  "status": "ok",
  "version": "3.0.0-alpha.0",
  "checks": {
    "db": "ok",
    "redis": "ok",
    "embeddings": "ok"
  }
}

Output (degraded)

{
  "status": "degraded",
  "checks": {
    "db": "ok",
    "redis": "degraded",
    "embeddings": "ok"
  }
}

The status strings are colorized in a terminal that supports ANSI escape codes.

mnemo config set <key> <value>

Persist a configuration value to ~/.mnemo/config.json.

Valid keys — url, apiKey, uiMode (delight, verbose, quiet).

Syntax

mnemo config set <key> <value>

Examples

mnemo config set url http://localhost:3939
mnemo config set apiKey msk_abc123xyz
mnemo config set uiMode delight

Output

✓ Set url

Exits with code 1 if an unknown key is supplied.

mnemo config get [key]

Read configuration values. The apiKey is always masked — only the last 4 characters are shown.

Syntax

mnemo config get           # print all values
mnemo config get url       # print a single value
mnemo config get apiKey    # print masked apiKey

Examples

$ mnemo config get
{
  "url": "http://localhost:3939",
  "apiKey": "****xyz"
}

$ mnemo config get url
http://localhost:3939

$ mnemo config get apiKey
****xyz

Prints (not set) for keys that have no value in either the config file or environment.

mnemo login [--url <url>] [--key <apiKey>]

Save server credentials to ~/.mnemo/config.json (created securely with mode 0600). Supports both interactive prompts and non-interactive flags:

# Non-interactive (scripting / CI):
npx -y @mnemo-ai/cli login --url https://mnemo.pablim.dev --key mns_live_...

# Interactive:
mnemo login

mnemo install

Automatically detect and configure all installed AI coding agents on this machine (Claude Code, Cursor, OpenCode, Codex, Gemini CLI):

npx -y @mnemo-ai/cli install

What mnemo install does:

1. Registers the MCP Server: Configures @mnemo-ai/mcp across all detected agents.
2. Installs Hooks & Skills: Automatically registers session hooks (session-start, user-prompt-submit, session-end) and cognitive skills for Claude Code, Cursor, and Gemini.

ℹ️ Manual JSON vs. Auto-Installer: Adding the mcpServers JSON block manually to Claude Desktop or Cursor registers the MCP tools, but does not install session hooks or skills. Use mnemo install for a complete automatic setup.

mnemo info / mnemo whoami

Display current session context, including connected server URL, active workspace ID, user identity, tenant role, and storage stats.

mnemo info

mnemo doctor

Run server-side diagnostics including API connectivity, RLS status, table grants, and embedding worker queues.

mnemo doctor

mnemo workspace list / mnemo workspace members <id>

List workspaces accessible to the authenticated user, or inspect workspace members.

mnemo workspace list
mnemo workspace members 00000000-0000-0000-0000-000000000001

mnemo keys <list|create|revoke|show|rotate>

Manage API keys for the active workspace:

mnemo keys list
mnemo keys create --label "CI Agent" --scopes memory:read,memory:write
mnemo keys rotate mk_abc123def456 "scheduled rotation"

mnemo list [--limit N]

List recent facts from the workspace, sorted by creation date descending. Default: 20 facts.

mnemo list
mnemo list --limit 50

mnemo search <query>

Full-text search without Claude. Uses the recall pipeline with FTS fallback — works even without MNEMO_LLM_API_KEY.

mnemo search "TypeScript generics"
mnemo search "bug fixed in auth"

mnemo show <factId>

Display all fields of a fact as pretty-printed JSON.

mnemo show mfact_abc123def456

mnemo sessions

List active and recent sessions for the workspace.

mnemo sessions

mnemo tasks

List tasks in the workspace.

mnemo tasks

mnemo events

List events recorded in the workspace log.

mnemo events

mnemo health

Show detailed health information including /health/ready and /v1/health endpoints. More detailed than mnemo status.

mnemo health

mnemo export

Export workspace memory as gzip-compressed JSONL to stdout. Pipe with gunzip to process:

mnemo export | gunzip | jq .
mnemo export > backup.jsonl.gz

mnemo import <file.jsonl.gz>

Import a previously exported JSONL archive. Supports --from mem0|zep|claude for third-party formats and --conflict-resolution skip|overwrite|newest.

mnemo import ./backup.jsonl.gz
mnemo import ./claude-memory.json --from claude
mnemo import ./export.jsonl.gz --conflict-resolution newest

mnemo init [--docker]

Setup wizard with two modes:

• Without --docker: prompts for server URL + API key, configures Claude Code MCP and Claude Desktop.
• With --docker: bootstraps a complete local stack — starts Docker (Postgres + Redis), runs migrations, generates an API key, configures MCP. Requires the Mnemosyne monorepo.

mnemo init             # cloud/manual mode
mnemo init --docker    # full local Docker bootstrap

mnemo link [--label <name>] [--force]

Write a .mnemo.json file in the current directory, pinning it to the active API key's workspace. Project-local config that SessionStart hooks (installed by mnemo install) auto-discover, so agents launched from this directory resolve the right workspace without re-running mnemo login.

mnemo link                        # pin cwd to the current workspace
mnemo link --label "backend-svc"  # optional human-readable label
mnemo link --force                # overwrite an existing .mnemo.json

Fails if .mnemo.json already exists (pass --force to overwrite), or if the active API key can't resolve a workspaceId (needs at least memory:read, same as mnemo whoami).

mnemo reset --workspace <id> --confirm

Runs a dry-run safety check for a workspace embedding-model reset (targetModel: "reset") — does not delete or mutate data. Blocked entirely when NODE_ENV=production, and requires explicit --confirm even outside production.

mnemo reset --workspace 3fa85f64-5717-4562-b3fc-2c963f66afa6 --confirm

mnemo completion <shell>

Generate shell completion scripts. Supported shells: bash, zsh, fish, pwsh.

mnemo completion bash >> ~/.bashrc
mnemo completion zsh >> ~/.zshrc
source <(mnemo completion fish)

mnemo help

Print the built-in command reference to stdout.

mnemo help
# or simply
mnemo

Exit Codes

| Code | Meaning | |------|---------------------------------------------------------------------------------| | 0 | Command completed successfully. | | 1 | Error — authentication failure, server unreachable, fact not found, config key missing, invalid usage, or unexpected runtime error. |

The error message is always written to stderr so it does not pollute stdout in scripts.

Scripting

Because mnemo writes clean output to stdout and errors to stderr, it integrates naturally into shell scripts.

Check whether a remember succeeded

if mnemo remember "Deploy completed at $(date -u +%Y-%m-%dT%H:%M:%SZ)"; then
  echo "Memory stored."
else
  echo "Failed to store memory." >&2
  exit 1
fi

Use environment variables for per-job credentials

MNEMO_URL=https://prod.example.com \
MNEMO_KEY=msk_yourkey \
mnemo status

Capture the ID from remember

The ID is embedded in the success line (✓ Remembered: <id>). Extract it with awk or sed:

OUTPUT=$(mnemo remember "fact goes here")
ID=$(echo "$OUTPUT" | awk '{print $NF}')
echo "Stored as: $ID"

Pipe recall output as JSON

mnemo recall with --json outputs structured JSON:

mnemo recall --json "user preferences" | jq '.hits[].statement'

Or call the HTTP API directly:

curl -s -X POST "$MNEMO_URL/v1/recall" \
  -H "Authorization: Bearer $MNEMO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "user preferences", "limit": 10}' \
  | jq '.memories.hits[].content'

Search without LLM (FTS fallback)

mnemo search uses full-text search even without an API key:

mnemo search "TypeScript strict mode"

Health check in CI

if ! mnemo status 2>/dev/null | grep -q '"ok"'; then
  echo "Mnemosyne not healthy — aborting." >&2
  exit 1
fi

License

Apache-2.0 — see LICENSE.