@mnemahq/cli

Connect a repository to your Mnema workspace: install Claude Code session capture (real token cost, git, files touched), backfill past sessions, and search your workspace — all from the terminal.

Quick start

npm install -g @mnemahq/cli
mnema init

The package is @mnemahq/cli; the command it installs is mnema. (The unscoped name mnema is blocked on npm — its typosquat filter rejects it as too close to the existing package mem.)

Run mnema login first and the workspace is filled in automatically. Otherwise you'll be asked for two values, which live on two different settings pages:

| value | where | | --- | --- | | Workspace id | Settings → Workspace | | Hook token | Settings → Access → Session capture → Generate token |

Optionally an API key for search. init installs the capture hook, stores your secrets in the OS keychain, and writes a .mnema/config.json (safe to commit — it holds no secrets).

Start a Claude Code session and it appears under Sessions with its cost.

Run from a checkout (contributors)

Hacking on the CLI inside the monorepo instead of installing the package? It's zero-build Node ESM — run it straight from bin/:

node packages/cli/bin/mnema.mjs init
node packages/cli/bin/mnema.mjs doctor        # verify the install

For a global mnema that tracks your working copy: cd packages/cli && npm link.

Non-interactive (CI or scripted setup) — pass the workspace id as a flag and the secrets as env vars so nothing is prompted:

MNEMA_HOOK_TOKEN=<hook-token> MNEMA_API_KEY=<api-key> \
  node packages/cli/bin/mnema.mjs init --workspace <workspace-id> --yes

--origin defaults to https://api.theboringpeople.in; point it (or MNEMA_API_ORIGIN) at your own host for a self-hosted instance.

Commands

| Command | What it does | | --- | --- | | mnema init | Link the repo, install session capture, store secrets | | mnema status | Connection, hook, API reachability, last session | | mnema sessions | Recent sessions for this repo (local + server) | | mnema sweep | Backfill past local sessions (opt-in, no history backfill) | | mnema pull | Export repo-bound docs into .mnema/context/**.md (committed, offline-readable) | | mnema search "q" | Search your workspace | | mnema doctor | Diagnose install, hooks, auth, connectivity | | mnema uninstall | Remove hooks and stored secrets (--purge also deletes .mnema/) |

Secrets & privacy

Secrets are stored in the OS keychain (macOS Keychain, libsecret on Linux); if none is available they fall back to a 0600 file under your config dir. A token is never written into the committed .mnema/config.json. The capture hook sends metadata and file paths only — never file contents. See the privacy details.

--origin <url> (or MNEMA_API_ORIGIN) points the CLI at a self-hosted instance.

Requires Node 20+ and git — the same floor @mnemahq/sdk already declares.

The interactive briefing

Run mnema with no arguments in a terminal and it opens a navigable briefing: pulse, then the ranked findings, with enter to drill into one.

mnema        the briefing (a terminal, Node 20+)
mnema tui    the same, explicitly
mnema --no-tui   print help instead

It never opens when output is piped, under CI, on TERM=dumb, or where the terminal cannot enter raw mode — in all of those mnema prints help exactly as it always has. MNEMA_TUI=never turns it off for good; MNEMA_TUI=always forces it.

Ink is loaded lazily, so this costs one-shot commands nothing: mnema --version measures the same before and after (~60ms), because ink is only imported once the UI is actually opening. Installed size is ~22 MB, most of which is es-toolkit arriving through Ink.

Output, piping and colour

Every read command takes --json, so the CLI composes:

mnema tasks --json | jq '.[] | select(.priority == "high") | .title'

Colour is emitted only when output is a terminal. mnema docs > out.txt and mnema tasks | grep … produce plain text with no escape sequences in it.

| variable | effect | | --- | --- | | NO_COLOR | disable colour, any value (no-color.org) | | FORCE_COLOR=1 | keep colour through a pipe, e.g. mnema tasks \| less -R | | COLUMNS | override the width used for column layout | | MNEMA_WORKSPACE_ID | default workspace, instead of --workspace |

mnema doc <id> is built for redirection: the markdown goes to stdout and the title and path go to stderr, so mnema doc <id> > note.md gets the document alone.

.mnema/ repo artifacts

mnema init scaffolds a committed .mnema/ directory and mnema pull fills it:

.mnema/
  config.json     workspace + repo binding (no secrets)
  NOTABILITY.md   editable prose describing what's worth capturing in this repo
  context/**.md   workspace docs bound to this repo — readable offline, diff in PRs
  manifest.json   sync bookkeeping (hashes only)

Sync is server-is-truth, but your local edits are never silently overwritten. On mnema pull: an untouched file is updated from the server; a file you edited while the server didn't change is kept as-is; if both changed, the server version is written beside yours as *.remote.md (gitignored) and the conflict is reported.