Metadata-Version: 2.4
Name: nmem-cli
Version: 0.9.4
Summary: CLI and TUI for Nowledge Mem - AI memory management
Project-URL: Homepage, https://mem.nowledge.co/
Project-URL: Repository, https://github.com/nowledge-co/
Project-URL: Documentation, https://mem.nowledge.co/docs
Author: Nowledge Labs
License-Expression: MIT
Keywords: ai,cli,knowledge-graph,mcp,memory,tui
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 :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: httpx>=0.25.0
Requires-Dist: pyperclip>=1.9.0
Requires-Dist: qrcode>=8.2
Requires-Dist: rich>=13.0.0
Requires-Dist: textual>=0.50.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# nmem-cli

A lightweight CLI and TUI for [Nowledge Mem](https://mem.nowledge.co/) - AI memory management that works with any AI agent.

## Installation Options

### Option 1: Standalone PyPI Package (Recommended for CLI-only users)

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

Or with uv:

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

### Option 2: Nowledge Mem Desktop App

If you're using the [Nowledge Mem desktop app](https://mem.nowledge.co/), the `nmem` CLI is bundled and can be installed via:

- **macOS**: Settings → Preferences → Developer Tools → Install CLI
- **Linux**: Automatically installed via package postinstall
- **Windows**: Automatically added to PATH during installation

The desktop app includes a bundled Python environment, so no separate Python installation is required.

## Requirements

- Python 3.11+ (for PyPI package)
- A running Nowledge Mem server (default: `http://127.0.0.1:14242`)

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

## Commands

### Core Commands

| Command | Description |
| ------- | ----------- |
| `nmem status` | Check server connection status |
| `nmem stats` | Show database statistics |
| `nmem tui` | Launch interactive terminal UI |

### Memory Commands

| Command | Description |
| ------- | ----------- |
| `nmem m` / `nmem memories` | List recent memories |
| `nmem m search "query"` | Search memories (includes source thread info) |
| `nmem m show <id>` | Show memory details |
| `nmem m add "content"` | Add a new memory |
| `nmem m add --stdin` | Add a memory from piped content |
| `nmem m update <id>` | Update a memory |
| `nmem m delete <id> [id ...]` | Delete one or more memories (bulk uses MCP) |
| `nmem m delete <id> --dry-run` | Preview what would be deleted |

### Thread Commands

| Command | Description |
| ------- | ----------- |
| `nmem t` / `nmem threads` | List recent threads |
| `nmem t list --source openclaw -n 20` | List recent threads for one source |
| `nmem t search "query"` | Search threads |
| `nmem t show <id>` | Show thread with messages |
| `nmem t create -t "Title" -c "content"` | Create a thread |
| `nmem t append <id> -m '[{"role":"user","content":"..."}]'` | Append messages to a thread |
| `nmem t save --from claude-code` | Save Claude Code session as thread |
| `nmem t save --from codex` | Save Codex session as thread |
| `nmem t save --from gemini-cli` | Save Gemini CLI session as thread |
| `nmem t sync --from codex --all-projects` | Preview historical Codex sessions across projects |
| `nmem t sync --from pi` | Preview historical Pi sessions |
| `nmem t sync --from pi --apply` | Import historical Pi sessions |
| `nmem t delete <id>` | Delete a thread |
| `nmem t delete <id> --dry-run` | Preview what would be deleted |

## Options

### Global Options

```bash
nmem --json <command>     # Output in JSON format (for scripting)
nmem --api-url <url>      # Override API URL
nmem --version            # Show version
```

### Search Filters (memories)

```bash
nmem m search "query" -l label1 -l label2   # Filter by labels
nmem m search "query" -t week               # Time range: today/week/month/year
nmem m search "query" --importance 0.7      # Minimum importance
```

## Persistent Remote Configuration

For long-term remote use, prefer `nmem`'s config file instead of exporting auth on every shell session.

The recommended CLI flow is:

```bash
nmem config client set url https://mem.example.com
nmem config client set api-key nmem_your_key
nmem config client show
```

This writes the same local client config file that integrations like Hermes, Cursor hooks, and OpenClaw read on this machine.

Create manually if needed:

```json
~/.nowledge-mem/config.json
```

With content:

```json
{
  "apiUrl": "https://mem.example.com",
  "apiKey": "nmem_your_key"
}
```

Resolution priority:

1. `--api-url`
2. `NMEM_API_URL` / `NMEM_API_KEY`
3. `~/.nowledge-mem/config.json`
4. defaults

Use environment variables when you want a temporary override for the current shell, CI job, or integration runtime.

`nmem config client ...` controls how this machine connects outward to Mem. It is separate from `nmem config access ...`, which controls how a Mem server is exposed to other devices on your network or through Access Anywhere.

## MCP Host Configuration

Direct HTTP MCP clients do not read `~/.nowledge-mem/config.json` by themselves. The host owns its MCP transport, so remote Mem needs headers in that host's MCP settings.

Generate the right snippet from the client config you already saved:

```bash
nmem config mcp show --host codex
nmem config mcp show --host gemini-cli
nmem config mcp show --host cursor
nmem config mcp show --host claude-desktop
```

For a fixed Mem space, add `--space "Research Agent"`. The generated snippet includes your API key when one is configured, so paste it only into the target host's private MCP config.

## Environment Variables

| Variable | Description | Default |
| -------- | ----------- | ------- |
| `NMEM_API_URL` | API server URL | `http://127.0.0.1:14242` |
| `NMEM_API_KEY` | Optional API key (Bearer auth + proxy-safe fallback) | _(unset)_ |

Remote tunnel examples:

```bash
# Quick Tunnel (random URL)
export NMEM_API_URL="https://<random>.trycloudflare.com"
export NMEM_API_KEY="nmem_..."

# Cloudflare account tunnel (stable URL)
export NMEM_API_URL="https://mem.example.com"
export NMEM_API_KEY="nmem_..."
```

For account mode, the URL is the Cloudflare `Route tunnel → Public Hostname` value (use domain root only, without `/remote-api`).

## TUI Features

The interactive TUI provides:

- **Dashboard**: Overview with statistics and recent activity
- **Memories**: Browse, search, and manage memories
- **Threads**: View conversation threads
- **Graph**: Explore the knowledge graph
- **Settings**: Configure the application

### TUI Keybindings

| Key | Action |
| --- | ------ |
| `1-5` | Switch tabs |
| `/` | Focus search |
| `?` | Show help |
| `q` | Quit |

## Agent and Pipeline Usage

`nmem` is designed to work well with AI agents and shell pipelines. Every input can be passed as a flag (no interactive prompts block automation), and `--json` mode gives structured output for programmatic consumption.

### Piping Content

```bash
# Pipe content into a new memory
echo "The auth service uses RS256 JWTs" | nmem m add --stdin -t "Auth notes" -l backend

# Pipe content into Working Memory
cat daily_focus.md | nmem wm patch --heading "## Focus Areas" --stdin
```

### Previewing Destructive Actions

```bash
# See what would be deleted (with titles) without making changes
nmem m delete mem-abc123 mem-def456 --dry-run
nmem t delete thread-xyz --cascade --dry-run
nmem s delete src-123 --dry-run
```

### Non-Interactive Provider Setup

```bash
# All config commands work without interactive menus
nmem config provider set anthropic --api-key sk-ant-...
nmem config provider set openai --api-key sk-... --model gpt-4o
nmem config provider activate anthropic
```

### Idempotent Appends

```bash
# Retry-safe thread updates with idempotency keys
nmem t append thread-abc \
  -m '[{"role":"assistant","content":"Finding"}]' \
  --idempotency-key batch-001
```

## Examples

### Script Integration (JSON mode)

```bash
# Get memories as JSON
nmem --json m search "meeting notes" | jq '.memories[].title'

# Get source thread for a memory (to fetch full conversation context)
nmem --json m search "auth" | jq '.memories[] | {title, thread: .source_thread.id}'

# Check if server is running
if nmem --json status | jq -e '.status == "ok"' > /dev/null; then
    echo "Server is running"
fi
```

### Adding Memories

```bash
# Simple memory
nmem m add "Remember to review the PR tomorrow"

# With title and importance
nmem m add "The deployment process requires SSH access" \
    -t "Deployment Notes" \
    -i 0.8

# With labels (repeatable -l flag)
nmem m add "API uses JWT tokens for auth" \
    -t "Auth Notes" \
    -l work -l backend

# With custom source (for skills/integrations)
nmem m add "User preference: dark mode" \
    -s "skill-settings"
```

Options for `nmem m add`:
- `-t, --title`: Memory title
- `-i, --importance`: Importance score 0.0-1.0 (default: 0.5)
- `-l, --label`: Add label (repeatable for multiple labels)
- `-s, --source`: Source identifier (default: "cli")
- `--stdin`: Read content from stdin instead of positional argument
- `--unit-type`: Knowledge type (`fact`, `preference`, `decision`, `plan`, `procedure`, `learning`, `context`, `event`)
- `--event-start`, `--event-end`: When the fact happened (YYYY, YYYY-MM, or YYYY-MM-DD)
- `--when`: Temporal context (`past`, `present`, `future`, `timeless`)

### Creating Threads

```bash
# From content
nmem t create -t "Debug Session" -c "Started investigating the memory leak"

# Explicit thread id (for deterministic integrations)
nmem t create --id openclaw-session-abc123 -t "OpenClaw Session" -c "Session started"

# From file
nmem t create -t "Code Review" -f review-notes.md

# Append one message
nmem t append openclaw-session-abc123 -c "Follow-up finding" -r assistant

# Append with retry-safe idempotency key
nmem t append openclaw-session-abc123 \
  -m '[{"role":"assistant","content":"Follow-up finding","metadata":{"external_id":"oc-msg-42"}}]' \
  --idempotency-key openclaw-run-123
```

### Saving AI Coding Sessions

Import conversations from Claude Code, Codex, Gemini CLI, OpenCode, or Pi as threads:

```bash
# Save current Claude Code session (uses current directory)
nmem t save --from claude-code

# Save from a specific project path
nmem t save --from claude-code -p /path/to/project

# Save all sessions for a project
nmem t save --from claude-code -m all

# Save Codex session with a summary
nmem t save --from codex -s "Implemented auth feature"

# Save Gemini CLI session from the current project
nmem t save --from gemini-cli

# Preview older Pi sessions, then import them
nmem t sync --from pi
nmem t sync --from pi --apply

# Preview older sessions across all projects for hosts with project-scoped storage
nmem t sync --from codex --all-projects --limit 20
nmem t sync --from claude-code --all-projects --limit 20
nmem t sync --from gemini-cli --all-projects --limit 20
nmem t sync --from opencode --all-projects --limit 20
```

How it works:

- `nmem` discovers and reads the local agent session files on the machine where you run the command
- it parses those transcripts into normalized thread messages
- it then uploads the resulting thread data to your configured Mem server

By default, Claude Code, Codex, and Pi are discovered from `~/.claude`, `~/.codex`, and `~/.pi/agent`. If you keep them somewhere else, `nmem` also respects `CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `PI_CODING_AGENT_DIR`, and `PI_CODING_AGENT_SESSION_DIR` automatically.

That means `nmem t save --from ...` works correctly with remote Mem too: the server does not need direct access to those local agent directories on your laptop.

Options:
- `--from`: Source app (`claude-code`, `codex`, `gemini-cli`, `opencode`, or `pi`) - required
- `-p, --project`: Project directory (default: current dir)
- `-m, --mode`: `current` (latest session) or `all` (all sessions)
- `-s, --summary`: Brief session summary
- `--session-id`: Specific session ID
- `--truncate`: Truncate large tool results (>10KB)

Use `nmem t sync --from ...` for deliberate historical backfills. It previews by default and requires `--apply` before writing. For Pi, `sync` scans all Pi sessions by default; pass `--session-dir` or `--project` to narrow it. For Claude Code, Codex, Gemini CLI, and OpenCode, the default stays scoped to the current project; add `--all-projects` when you intentionally want a broader import.

Re-running the command is safe. Each discovered session is processed independently. If a previous run stopped halfway through a batch, or created a thread but stopped before the batch finished, the next run detects the existing thread and appends with deduplication. If another process creates the thread between the existence check and the create request, the command falls through to the same deduplicated append path. Stable thread IDs, stable per-message `external_id`s, and an idempotency key keep repeated imports from duplicating messages.

This import path is distinct from desktop auto-sync and watcher-based ingestion:

- desktop auto-sync watches transcript files on the same machine as the Mem server
- plugin hooks and `nmem t save` / `nmem t sync` run on the machine where the agent is running, then upload to local or remote Mem through the same client config
- all paths use the same canonical source and thread IDs, so rerunning a hook, desktop watcher, or historical sync appends to the same thread instead of creating duplicates

Use the client-side path for remote Mem. A remote Mem server cannot scan your laptop's `~/.codex`, `~/.claude`, `~/.gemini`, `~/.pi`, or OpenCode session database by itself.

## Related

- [Nowledge Mem](https://mem.nowledge.co/) - The full Nowledge Mem application
- This CLI is also bundled with the main Nowledge Mem desktop app

## Author

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