nmem-cli

A lightweight, single-binary CLI for Nowledge Mem - AI memory management that works with any AI agent.

Now a compiled binary. As of the 0.10.0 line, nmem-cli ships the Rust-built nmem binary instead of a Python module. pip install nmem-cli downloads a platform wheel that contains the compiled CLI and puts nmem on your PATH. There is no Python runtime requirement beyond pip itself, and no Python dependencies are installed. The command surface and behavior are unchanged.

Installation

pip install nmem-cli

Or with uv:

uv tool install nmem-cli   # or: uv pip install nmem-cli

The wheel bundles the compiled nmem binary for your platform (macOS arm64/x86_64, Linux x86_64/aarch64, Windows x64). No separate toolchain or interpreter is needed.

If you use the Nowledge Mem desktop app, the nmem CLI is already bundled and can be installed from Settings → Developer Tools → Install CLI (macOS), or automatically on Linux/Windows.

Requirements

• Most commands require a running Nowledge Mem backend (default: http://127.0.0.1:14242), local or remote. Plugin inspection is local-only and does not require the backend.

Quick Start

# Check server status
nmem status

# Launch interactive TUI
nmem tui

# List memories
nmem m

# Search memories
nmem m search "python programming"

# List threads
nmem t

# Rename a saved thread on a server with Thread rename enabled
nmem t rename '<thread-id>' --title "Research notes"

# Show version
nmem --version

See the full command reference and JSON/agent usage at mem.nowledge.co/docs.

Thread rename requires a supporting server with NMEM_THREAD_TITLE_UPDATE_ENABLED=1 (default off). Set that flag on the server, not only in the CLI shell. Rename finds the unique readable Thread and its Space from the ID, ignoring ambient Space defaults. Optionally restrict the lookup with --space-id or --space (not both); ambiguous IDs and servers without unique-identity proof are refused before writing. REST/MCP writes still require the exact Space and storage ID. A changed manual title survives later sync and automatic review. An identical title is a no-op. See the Thread title contract for identity checks, validation, MCP access and deferred Search repair.

Where writes land and which Space to name

nmem m add reports the Space a Memory was saved to, by label and exact ID (Saved to Research (team-research)). In a team workspace a write that names no Space is saved to your personal space; the CLI then prints Saved to Only me (...) and the --space <name> that would share it. --json adds space_id, space (id, label, kind) and share_hint. nmem spaces list shows each Space's exact ID and kind. NMEM_SPACE, NMEM_SPACE_ID and the configured Space still place writes exactly as before; writes that rely on them are declared ambient (x-nmem-space-origin: ambient) so the server can count them ahead of the planned change described in docs/design/TEAM_SPACES_ROOM_MODEL.md section 6. In a team workspace an explicit default Space is deprecated and is saved to your personal space.

Cloud Agent messaging (internal pilot)

An admitted Cloud Agent can use nmem mailbox cloud --space-id '<exact-id>' (or --space '<name or alias>', resolved once and echoed as the exact ID) to inspect its identity (context), explicitly register its mailbox (register), find authorized recipient cards (recipients), send or reply (send), and read its own mail (summary, inbox, show). Use the pilot operator's qualified HTTPS destination and your own standard Agent key. This is an identity mailbox; it does not create or impersonate a harness session.

Registration and sends require a stable --request-id. Keep the ID and all original arguments before calling; an uncertain result must not become a new send with a new ID. Sending requires the exact chosen --recipient handle and --revision. After show, use reply-target --actor-id '<your-actor-id>' '<message-id>' to obtain the original sender's current card; send with that unchanged card and --reply-to '<message-id>'. If the sender is unavailable, do not substitute another identity. After an uncertain reply, preserve and retry the original send, including its first card; do not resolve a fresh selection. A receipt means mailbox acceptance, not that another model read it or completed the task. Passive reads do not acknowledge delivery. Ordinary OAuth knowledge connections are not admitted.

The containing Cloud APIs must be deployed and qualified before this client is published. See the internal Bridge guide for the candidate workflow and remaining recovery limitations.

When the shared Bridge feature flag refuses this account with the typed feature_disabled cause, the CLI skips the operation: exit status 0, empty stdout (including --json), and one stderr warning: Warning: Nowledge Bridge isn't enabled for this account. This applies to all Bridge CLI commands, including writes such as send, prepare and resume. Automatic mailbox probe is fully silent. An empty result means the capability was skipped; it supplies no accepted or delivered evidence. Automation that needs confirmation must inspect the actual operation result or retained original. Other authorization, policy-service, configuration and transport errors retain their existing failure behavior. HTTP reports the typed feature_disabled denial. MCP hides unavailable Bridge tools from discovery; direct calls refused by its catalog gate return JSON-RPC -32602 (unknown tool).

For agent integrations

Run plugin inspection in the same user profile and project environment as the agent. First discover which host adapters this version of the CLI supports:

nmem --json plugins inspect --list-hosts

The response contains schema_version, local_only, and hosts, an array of canonical id values with accepted input aliases. For example, codex-cli accepts codex. Use the canonical ID to inspect one host:

nmem --json plugins inspect --host codex-cli --cwd /path/to/project

The catalog says only that this CLI can inspect that host; it does not prove that Nowledge Mem is installed, enabled, or loaded there. Decide whether to offer setup from the inspection result's installation and recommended_action, not from catalog membership or exit status alone. Older CLI releases may not have --list-hosts; probe the command and handle an unsupported-argument error rather than assuming a minimum version before the first release carrying this feature.

Local App experiments

With Nowledge Mem running and the CLI connected to this computer's local backend:

nmem labs
nmem labs enable team-lite
nmem labs disable team-lite
nmem labs enable bridge
nmem labs disable bridge
nmem labs enable hawdb
nmem labs prepare hawdb
nmem labs disable hawdb
nmem --json labs

These controls cover Team Lite, Nowledge Bridge and HawDB. They default off; Passkeys are outside this command. Cloud and remote connections print a warning and perform no action. Older or absent Apps require an update/start before these commands can work; the CLI never edits preference files as a fallback.

HawDB enable requests legacy-primary mirroring. It does not select HawDB as the primary, import data or restart the App. Preparation is an explicit independent Native action and can stop the local backend; nmem labs still observes its retained progress. Restart the App when preparation reports that it is needed. Unsafe primary-mode changes refuse. Bridge disable retains messages and Agent identities. All results distinguish requested preference from actual runtime. If a mutation response is lost, inspect status before retrying.

See the device-local control contract.

Connecting to a backend

# Local (default)
nmem status

# Remote, one-off
nmem --api-url https://mem.example.com status

# Remote, persisted
nmem config client set url https://mem.example.com
nmem config client set api-key nmem_your_key

Resolution priority: --api-url > NMEM_API_URL / NMEM_API_KEY > ~/.nowledge-mem/config.json > defaults.

Related

• Nowledge Mem - the full application
• This CLI is also bundled with the Nowledge Mem desktop app

Author

Nowledge Labs

License

MIT