Metadata-Version: 2.4
Name: nmem-cli
Version: 0.6.5
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: 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 → Install CLI (creates `/usr/local/bin/nmem`)
- **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 update <id>` | Update a memory |
| `nmem m delete <id> [id ...]` | Delete one or more memories (bulk uses MCP) |

### Thread Commands

| Command | Description |
| ------- | ----------- |
| `nmem t` / `nmem threads` | List threads |
| `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 delete <id>` | Delete a thread |

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

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

## 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")

### 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 or Codex 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"
```

Options:
- `--from`: Source app (`claude-code` or `codex`) - 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 (Codex only)
- `--truncate`: Truncate large tool results (>10KB)

Re-running the command appends new messages with deduplication.

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