Metadata-Version: 2.4
Name: nmem-cli
Version: 0.10.113
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Rust
Classifier: Topic :: Utilities
Summary: CLI and TUI for Nowledge Mem - AI memory management
Keywords: cli,tui,memory,ai,knowledge-graph,mcp
Author: Nowledge Labs
License-Expression: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://mem.nowledge.co/docs
Project-URL: Homepage, https://mem.nowledge.co/
Project-URL: Repository, https://github.com/nowledge-co/

# nmem-cli

A lightweight, single-binary CLI for [Nowledge Mem](https://mem.nowledge.co/) - 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

```bash
pip install nmem-cli
```

Or with uv:

```bash
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](https://mem.nowledge.co/), 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

```bash
# 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

# Show version
nmem --version
```

See the full command reference and JSON/agent usage at
[mem.nowledge.co/docs](https://mem.nowledge.co/docs).

## Cloud Agent messaging (internal pilot)

An admitted Cloud Agent can use `nmem mailbox cloud --space-id '<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](../../../../docs/implementation/CLOUD_BRIDGE_INTERNAL_GUIDE.md)
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:

```bash
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:

```bash
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.

## Connecting to a backend

```bash
# 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](https://mem.nowledge.co/) - the full application
- This CLI is also bundled with the Nowledge Mem desktop app

## Author

[Nowledge Labs](https://github.com/nowledge-co)

## License

MIT

