nmem-cli 0.9.3

CLI and TUI for Nowledge Mem - AI memory management

nmem-cli

A lightweight CLI and TUI for Nowledge Mem - AI memory management that works with any AI agent.

Installation Options

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

pip install nmem-cli

Or with uv:

uv pip install nmem-cli

Option 2: Nowledge Mem Desktop App

If you're using the Nowledge Mem desktop app, 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

# 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

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

Search Filters (memories)

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:

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:

~/.nowledge-mem/config.json

With content:

{
  "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:

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:

# 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

# 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

# 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

# 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

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

# 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

# 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

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

# 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_ids, 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 - The full Nowledge Mem application
• This CLI is also bundled with the main Nowledge Mem desktop app

Author

Nowledge Labs