Command-line interface for Nowledge Mem — terminal access, scripting, and AI agent integration.

The nmem CLI gives you terminal access to your Nowledge Mem knowledge base. Search memories, browse threads, read and edit Working Memory, explore the knowledge graph, and view your activity feed — all from the shell.

Installation

Option 1: Standalone PyPI Package

Install on any machine — works with a local or remote Nowledge Mem server:

pip install nmem-cli

# or with uv
uv pip install nmem-cli

# or run without installing
uvx --from nmem-cli nmem --help

Requirements: Python 3.11+, Nowledge Mem running locally or reachable remotely.

Remote Access

The standalone package lets you reach your Nowledge Mem from servers, CI/CD pipelines, or remote workstations. See Access Mem Anywhere. View on PyPI.

Option 2: Bundled with Desktop App

macOS

Go to Settings → Preferences → Developer Tools and click Install CLI.

Installs to ~/.local/bin/nmem. Make sure ~/.local/bin is on your PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

0:00

--:--

Windows

The CLI is automatically available after app installation. Open a new terminal window to use nmem.

Linux

Included with deb/rpm packages. The binary is placed in /usr/local/bin/nmem.

Quick Start

nmem status                              # Check connection
nmem m search "project notes"           # Search memories
nmem m add "Key insight" --title "Learning"
nmem wm                                  # Read today's Working Memory
nmem f --days 1                          # Today's activity
nmem g expand <memory-id>               # Explore graph connections
nmem tui                                 # Interactive terminal UI

Global Options

Option	Description
`-j, --json`	Machine-readable JSON output
`--api-url <url>`	API URL (default: `http://127.0.0.1:14242`)
`-v, --version`	Show version
`-h, --help`	Show help

Aliases: m = memories · t = threads · wm = working-memory · g = graph · f = feed · c = communities

Memory Commands (`nmem m`)

List memories

nmem m                        # Recent 10 memories
nmem m -n 50                  # List 50
nmem m --importance 0.7       # Minimum importance filter

Search

nmem m search "authentication patterns"
nmem m search "API design" --importance 0.8
nmem m search "deploy" -l devops -l backend    # Filter by labels (AND)
nmem m search "sprint" --mode deep             # Graph + LLM-enhanced results

Bi-temporal search — distinguish when something happened from when you saved it:

nmem m search "database decision" --event-from 2025-01 --event-to 2025-06
nmem m search "meeting notes" --recorded-from 2026-01-01

Option	Description
`-n`	Max results
`-l, --label`	Filter by label (repeatable)
`--importance`	Minimum importance (0–1)
`--mode`	`normal` (default, fast) or `deep` (graph + LLM-enhanced)
`--event-from/to`	When the fact happened (YYYY, YYYY-MM, or YYYY-MM-DD)
`--recorded-from/to`	When it was saved to Nowledge Mem (YYYY-MM-DD)

Add

nmem m add "We chose PostgreSQL for task events"
nmem m add "Prefer functional components in React" \
  --title "Frontend conventions" \
  --unit-type preference \
  --importance 0.8 \
  -l frontend -l react

# Record when something actually happened (bi-temporal)
nmem m add "Decided to sunset the legacy API" \
  --unit-type decision \
  --event-start 2025-11 \
  --when past

Option	Description
`-t, --title`	Memory title
`-i, --importance`	Importance 0–1
`-l, --label`	Add label (repeatable)
`--unit-type`	`fact` `preference` `decision` `plan` `procedure` `learning` `context` `event`
`--event-start`	When it happened (YYYY, YYYY-MM, YYYY-MM-DD)
`--event-end`	End of a time range
`--when`	`past` `present` `future` `timeless` (default: timeless)

Show

nmem m show <id>
nmem m show <id> --content-limit 500

Update

nmem m update <id> --title "New title"
nmem m update <id> --importance 0.9
nmem m update <id> --content "Updated content"

Delete

nmem m delete <id>
nmem m delete <id> -f          # Skip confirmation
nmem m delete <id1> <id2>      # Multiple IDs

Thread Commands (`nmem t`)

List and search

nmem t                                  # Recent 20 threads
nmem t -n 50
nmem t search "architecture decisions"

Show

nmem t show <id>
nmem t show <id> -m 50                 # Show up to 50 messages
nmem t show <id> --content-limit 200

Create

# From text
nmem t create -t "Quick note" -c "Remember to review the API changes"

# From a file
nmem t create -t "Meeting notes" -f notes.md

# With structured messages
nmem t create -t "Chat session" \
  -m '[{"role":"user","content":"Hello"},{"role":"assistant","content":"Hi!"}]'

# With a stable ID (idempotent — safe to re-run)
nmem t create -t "OpenClaw session" --id "openclaw-abc123-session"

Append

Add messages to an existing thread. Safely idempotent — duplicate messages are filtered by content hash or external ID.

# Single message
nmem t append <id> -c "Follow-up note"

# Structured messages
nmem t append <id> \
  -m '[{"role":"user","content":"Question"},{"role":"assistant","content":"Answer"}]'

# With idempotency key (safe for retries / repeated hook fires)
nmem t append <id> \
  -m '[{"role":"user","content":"msg"}]' \
  --idempotency-key "oc-batch-session-001"

Save Claude Code / Codex session

nmem t save --from claude-code         # Save Claude Code session
nmem t save --from codex               # Save Codex session
nmem t save --from codex -s "Summary"  # With session summary

Option	Description
`--from`	`claude-code` or `codex` (required)
`-p, --project`	Project directory path (default: current dir)
`-m, --mode`	`current` (latest) or `all` sessions
`--session-id`	Specific session ID (Codex only)
`-s, --summary`	Brief session summary
`--truncate`	Truncate large tool results (>10KB)

Delete

nmem t delete <id>
nmem t delete <id> -f                  # Force
nmem t delete <id> --cascade           # Also delete associated memories

Working Memory (`nmem wm`)

Working Memory is the AI-generated daily briefing — focus areas, open questions, and recent activity. The Knowledge Agent updates it each morning.

Read

nmem wm                                # Today's Working Memory
nmem wm --date 2026-02-12             # Archived date
nmem wm history                        # List available archived dates

Edit

nmem wm edit                           # Opens $EDITOR
nmem wm edit -m "## Focus Areas\n- Ship v0.6"   # Set directly

Patch a section (non-destructive)

Replace or append to one section without touching the rest of the document:

# Replace a section
nmem wm patch --heading "## Focus Areas" --content "- Finish OpenClaw plugin release"

# Append to a section
nmem wm patch --heading "## Notes" --append "Reminder: deploy to staging tonight"

The heading is matched case-insensitively and partially — "Focus" matches "## Focus Areas".

Graph Commands (`nmem g`)

Expand graph neighborhood

Explore connected memories, entities, crystals, and source documents around a given memory:

nmem g expand <memory-id>
nmem g expand <memory-id> --depth 2   # Two hops out
nmem g expand <memory-id> -n 10       # Limit neighbors per hop

Show EVOLVES version chain

See how a memory has been refined or superseded over time:

nmem g evolves <memory-id>

Feed (`nmem f`)

The activity feed shows what was saved, learned, synthesized, or ingested — chronologically.

nmem f                                  # Last 7 days (high-signal events)
nmem f --days 1                         # Today only
nmem f --days 30                        # Last 30 days
nmem f --type crystal_created           # Only crystal synthesis events
nmem f --from 2026-02-10 --to 2026-02-14   # Exact date range
nmem f --all                            # Include low-signal background events
nmem f -n 50                            # Limit events (default: 100)

Option	Description
`--days`	How many days back (default: 7; use 1 for today)
`--type`	Filter by event type
`-n, --limit`	Max events to fetch (default: 100)
`--all`	Include low-signal background events
`--from`, `--to`	Exact date range (YYYY-MM-DD)

Event types: memory_created · crystal_created · insight_generated · source_ingested · source_extracted · daily_briefing · url_captured

Knowledge Communities (`nmem c`)

Browse topic clusters automatically detected in your knowledge graph:

nmem c                                  # List communities
nmem c -n 20
nmem c show <community-id>              # Show community details (entities, memories)
nmem c detect                            # Trigger community detection (background)

Configuration & Models

Embedding model

nmem models status                      # Check current model status
nmem models download                    # Download the embedding model
nmem models reindex                     # Rebuild the search index

LLM provider

nmem config provider list
nmem config provider set openai --api-key sk-xxx --model gpt-4o
nmem config provider test

Processing settings

nmem config settings                               # Show all settings
nmem config settings set briefingHour 8            # Change morning briefing time

License

nmem license status
nmem license activate <key> <email>
nmem license deactivate                 # Deactivate license on this device

Remote Access

# LAN / private network
export NMEM_API_URL=http://192.168.1.100:14242
nmem status

# Cloudflare tunnel (from desktop app: Settings → Access Mem Anywhere)
export NMEM_API_URL=https://<your-url>
export NMEM_API_KEY=nmem_...
nmem m search "notes"

# One-off without env vars
nmem --api-url https://<your-url> status

Variable	Description	Default
`NMEM_API_URL`	API server URL	`http://127.0.0.1:14242`
`NMEM_API_KEY`	API key (Bearer auth)	(unset)

Full guide: Access Mem Anywhere.

JSON Output

Add --json (or -j) before the subcommand for machine-readable output:

nmem --json m search "API design" | jq '.memories[0].id'
nmem --json m add "Note" | jq -r '.id'
nmem --json f --days 1 | jq '.events[].title'

Search response

{
  "query": "API design",
  "total": 3,
  "search_mode": "fast_bm25_vector",
  "memories": [
    {
      "id": "abc123-def456-...",
      "title": "REST API versioning decision",
      "content": "We use /v1/ prefix for all public endpoints...",
      "score": 0.91,
      "relevance_reason": "Text Match (89%) + Semantic Match (73%) | decay[imp:high]",
      "importance": 0.8,
      "labels": ["architecture", "api"],
      "event_start": "2025-09",
      "temporal_context": "past",
      "source": "cli"
    }
  ]
}

Feed response

{
  "events": [
    {
      "id": "evt-...",
      "event_type": "memory_created",
      "severity": "info",
      "title": "Memory or event title",
      "description": "Summary text...",
      "metadata": { "source": "claude", "unit_type": "fact" },
      "related_memory_ids": ["..."],
      "created_at": "2026-02-20T02:35:28+00:00"
    }
  ]
}

Error response

{
  "error": "api_error",
  "status_code": 404,
  "detail": "Memory not found"
}

Status and Statistics

nmem status
# nmem v0.6.2
#   status   ok
#   api      http://127.0.0.1:14242
#   database connected

nmem stats
# Database Statistics
#   memories    83
#   threads     27
#   entities    248
#   labels      177
#   communities 32

AI Agent Integration

The --json flag and stable exit codes make nmem easy to drive from AI agents.

# Search for context before responding
nmem --json m search "authentication flow" | jq '.memories[:3]'

# Save an insight
nmem m add "Rate limiting is per-user, not per-IP" \
  --unit-type learning --importance 0.8 -l backend

# Save a decision with when it was made
nmem m add "Chose Postgres over MySQL for task events" \
  --unit-type decision --event-start 2026-02 -l architecture

# Browse what was worked on last week
nmem --json f --days 7 | jq '.events[].title'

# Create a session thread backup
nmem t create -t "Debug session $(date +%Y%m%d)" \
  -m '[{"role":"user","content":"Investigate auth failures"},{"role":"assistant","content":"Found rate limit issue"}]'

TUI

An interactive terminal UI for browsing memories, threads, and the knowledge graph:

nmem tui

nmem tui main nmem tui memory nmem tui thread nmem tui graph

Troubleshooting

"command not found: nmem"

PyPI install: pip install nmem-cli (Python 3.11+)
Run without installing: uvx --from nmem-cli nmem --help
macOS desktop: Settings → Preferences → Developer Tools → Install CLI → then ensure ~/.local/bin is on your PATH
Windows: open a new terminal after app installation

"Cannot connect to server"

Ensure Nowledge Mem is running
Try: nmem --api-url http://127.0.0.1:14242 status
Check for proxy or VPN blocking localhost

Installation

Option 1: Standalone PyPI Package

Install on any machine — works with a local or remote Nowledge Mem server:

pip install nmem-cli

# or with uv
uv pip install nmem-cli

# or run without installing
uvx --from nmem-cli nmem --help

Requirements: Python 3.11+, Nowledge Mem running locally or reachable remotely.

Remote Access

The standalone package lets you reach your Nowledge Mem from servers, CI/CD pipelines, or remote workstations. See Access Mem Anywhere. View on PyPI.

Option 2: Bundled with Desktop App

macOS

Go to Settings → Preferences → Developer Tools and click Install CLI.

Installs to ~/.local/bin/nmem. Make sure ~/.local/bin is on your PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

0:00

--:--

Windows

The CLI is automatically available after app installation. Open a new terminal window to use nmem.

Linux

Included with deb/rpm packages. The binary is placed in /usr/local/bin/nmem.

Quick Start

nmem status                              # Check connection
nmem m search "project notes"           # Search memories
nmem m add "Key insight" --title "Learning"
nmem wm                                  # Read today's Working Memory
nmem f --days 1                          # Today's activity
nmem g expand <memory-id>               # Explore graph connections
nmem tui                                 # Interactive terminal UI

Global Options

Option	Description
`-j, --json`	Machine-readable JSON output
`--api-url <url>`	API URL (default: `http://127.0.0.1:14242`)
`-v, --version`	Show version
`-h, --help`	Show help

Aliases: m = memories · t = threads · wm = working-memory · g = graph · f = feed · c = communities

Memory Commands (`nmem m`)

List memories

nmem m                        # Recent 10 memories
nmem m -n 50                  # List 50
nmem m --importance 0.7       # Minimum importance filter

Search

nmem m search "authentication patterns"
nmem m search "API design" --importance 0.8
nmem m search "deploy" -l devops -l backend    # Filter by labels (AND)
nmem m search "sprint" --mode deep             # Graph + LLM-enhanced results

Bi-temporal search — distinguish when something happened from when you saved it:

nmem m search "database decision" --event-from 2025-01 --event-to 2025-06
nmem m search "meeting notes" --recorded-from 2026-01-01

Option	Description
`-n`	Max results
`-l, --label`	Filter by label (repeatable)
`--importance`	Minimum importance (0–1)
`--mode`	`normal` (default, fast) or `deep` (graph + LLM-enhanced)
`--event-from/to`	When the fact happened (YYYY, YYYY-MM, or YYYY-MM-DD)
`--recorded-from/to`	When it was saved to Nowledge Mem (YYYY-MM-DD)

Add

nmem m add "We chose PostgreSQL for task events"
nmem m add "Prefer functional components in React" \
  --title "Frontend conventions" \
  --unit-type preference \
  --importance 0.8 \
  -l frontend -l react

# Record when something actually happened (bi-temporal)
nmem m add "Decided to sunset the legacy API" \
  --unit-type decision \
  --event-start 2025-11 \
  --when past

Option	Description
`-t, --title`	Memory title
`-i, --importance`	Importance 0–1
`-l, --label`	Add label (repeatable)
`--unit-type`	`fact` `preference` `decision` `plan` `procedure` `learning` `context` `event`
`--event-start`	When it happened (YYYY, YYYY-MM, YYYY-MM-DD)
`--event-end`	End of a time range
`--when`	`past` `present` `future` `timeless` (default: timeless)

Show

nmem m show <id>
nmem m show <id> --content-limit 500

Update

nmem m update <id> --title "New title"
nmem m update <id> --importance 0.9
nmem m update <id> --content "Updated content"

Delete

nmem m delete <id>
nmem m delete <id> -f          # Skip confirmation
nmem m delete <id1> <id2>      # Multiple IDs

Thread Commands (`nmem t`)

List and search

nmem t                                  # Recent 20 threads
nmem t -n 50
nmem t search "architecture decisions"

Show

nmem t show <id>
nmem t show <id> -m 50                 # Show up to 50 messages
nmem t show <id> --content-limit 200

Create

# From text
nmem t create -t "Quick note" -c "Remember to review the API changes"

# From a file
nmem t create -t "Meeting notes" -f notes.md

# With structured messages
nmem t create -t "Chat session" \
  -m '[{"role":"user","content":"Hello"},{"role":"assistant","content":"Hi!"}]'

# With a stable ID (idempotent — safe to re-run)
nmem t create -t "OpenClaw session" --id "openclaw-abc123-session"

Append

Add messages to an existing thread. Safely idempotent — duplicate messages are filtered by content hash or external ID.

# Single message
nmem t append <id> -c "Follow-up note"

# Structured messages
nmem t append <id> \
  -m '[{"role":"user","content":"Question"},{"role":"assistant","content":"Answer"}]'

# With idempotency key (safe for retries / repeated hook fires)
nmem t append <id> \
  -m '[{"role":"user","content":"msg"}]' \
  --idempotency-key "oc-batch-session-001"

Save Claude Code / Codex session

nmem t save --from claude-code         # Save Claude Code session
nmem t save --from codex               # Save Codex session
nmem t save --from codex -s "Summary"  # With session summary

Option	Description
`--from`	`claude-code` or `codex` (required)
`-p, --project`	Project directory path (default: current dir)
`-m, --mode`	`current` (latest) or `all` sessions
`--session-id`	Specific session ID (Codex only)
`-s, --summary`	Brief session summary
`--truncate`	Truncate large tool results (>10KB)

Delete

nmem t delete <id>
nmem t delete <id> -f                  # Force
nmem t delete <id> --cascade           # Also delete associated memories

Working Memory (`nmem wm`)

Working Memory is the AI-generated daily briefing — focus areas, open questions, and recent activity. The Knowledge Agent updates it each morning.

Read

nmem wm                                # Today's Working Memory
nmem wm --date 2026-02-12             # Archived date
nmem wm history                        # List available archived dates

Edit

nmem wm edit                           # Opens $EDITOR
nmem wm edit -m "## Focus Areas\n- Ship v0.6"   # Set directly

Patch a section (non-destructive)

Replace or append to one section without touching the rest of the document:

# Replace a section
nmem wm patch --heading "## Focus Areas" --content "- Finish OpenClaw plugin release"

# Append to a section
nmem wm patch --heading "## Notes" --append "Reminder: deploy to staging tonight"

The heading is matched case-insensitively and partially — "Focus" matches "## Focus Areas".

Graph Commands (`nmem g`)

Expand graph neighborhood

Explore connected memories, entities, crystals, and source documents around a given memory:

nmem g expand <memory-id>
nmem g expand <memory-id> --depth 2   # Two hops out
nmem g expand <memory-id> -n 10       # Limit neighbors per hop

Show EVOLVES version chain

See how a memory has been refined or superseded over time:

nmem g evolves <memory-id>

Feed (`nmem f`)

The activity feed shows what was saved, learned, synthesized, or ingested — chronologically.

nmem f                                  # Last 7 days (high-signal events)
nmem f --days 1                         # Today only
nmem f --days 30                        # Last 30 days
nmem f --type crystal_created           # Only crystal synthesis events
nmem f --from 2026-02-10 --to 2026-02-14   # Exact date range
nmem f --all                            # Include low-signal background events
nmem f -n 50                            # Limit events (default: 100)

Option	Description
`--days`	How many days back (default: 7; use 1 for today)
`--type`	Filter by event type
`-n, --limit`	Max events to fetch (default: 100)
`--all`	Include low-signal background events
`--from`, `--to`	Exact date range (YYYY-MM-DD)

Event types: memory_created · crystal_created · insight_generated · source_ingested · source_extracted · daily_briefing · url_captured

Knowledge Communities (`nmem c`)

Browse topic clusters automatically detected in your knowledge graph:

nmem c                                  # List communities
nmem c -n 20
nmem c show <community-id>              # Show community details (entities, memories)
nmem c detect                            # Trigger community detection (background)

Configuration & Models

Embedding model

nmem models status                      # Check current model status
nmem models download                    # Download the embedding model
nmem models reindex                     # Rebuild the search index

LLM provider

nmem config provider list
nmem config provider set openai --api-key sk-xxx --model gpt-4o
nmem config provider test

Processing settings

nmem config settings                               # Show all settings
nmem config settings set briefingHour 8            # Change morning briefing time

License

nmem license status
nmem license activate <key> <email>
nmem license deactivate                 # Deactivate license on this device

Remote Access

# LAN / private network
export NMEM_API_URL=http://192.168.1.100:14242
nmem status

# Cloudflare tunnel (from desktop app: Settings → Access Mem Anywhere)
export NMEM_API_URL=https://<your-url>
export NMEM_API_KEY=nmem_...
nmem m search "notes"

# One-off without env vars
nmem --api-url https://<your-url> status

Variable	Description	Default
`NMEM_API_URL`	API server URL	`http://127.0.0.1:14242`
`NMEM_API_KEY`	API key (Bearer auth)	(unset)

Full guide: Access Mem Anywhere.

JSON Output

Add --json (or -j) before the subcommand for machine-readable output:

nmem --json m search "API design" | jq '.memories[0].id'
nmem --json m add "Note" | jq -r '.id'
nmem --json f --days 1 | jq '.events[].title'

Search response

{
  "query": "API design",
  "total": 3,
  "search_mode": "fast_bm25_vector",
  "memories": [
    {
      "id": "abc123-def456-...",
      "title": "REST API versioning decision",
      "content": "We use /v1/ prefix for all public endpoints...",
      "score": 0.91,
      "relevance_reason": "Text Match (89%) + Semantic Match (73%) | decay[imp:high]",
      "importance": 0.8,
      "labels": ["architecture", "api"],
      "event_start": "2025-09",
      "temporal_context": "past",
      "source": "cli"
    }
  ]
}

Feed response

{
  "events": [
    {
      "id": "evt-...",
      "event_type": "memory_created",
      "severity": "info",
      "title": "Memory or event title",
      "description": "Summary text...",
      "metadata": { "source": "claude", "unit_type": "fact" },
      "related_memory_ids": ["..."],
      "created_at": "2026-02-20T02:35:28+00:00"
    }
  ]
}

Error response

{
  "error": "api_error",
  "status_code": 404,
  "detail": "Memory not found"
}

Status and Statistics

nmem status
# nmem v0.6.2
#   status   ok
#   api      http://127.0.0.1:14242
#   database connected

nmem stats
# Database Statistics
#   memories    83
#   threads     27
#   entities    248
#   labels      177
#   communities 32

AI Agent Integration

The --json flag and stable exit codes make nmem easy to drive from AI agents.

# Search for context before responding
nmem --json m search "authentication flow" | jq '.memories[:3]'

# Save an insight
nmem m add "Rate limiting is per-user, not per-IP" \
  --unit-type learning --importance 0.8 -l backend

# Save a decision with when it was made
nmem m add "Chose Postgres over MySQL for task events" \
  --unit-type decision --event-start 2026-02 -l architecture

# Browse what was worked on last week
nmem --json f --days 7 | jq '.events[].title'

# Create a session thread backup
nmem t create -t "Debug session $(date +%Y%m%d)" \
  -m '[{"role":"user","content":"Investigate auth failures"},{"role":"assistant","content":"Found rate limit issue"}]'

TUI

An interactive terminal UI for browsing memories, threads, and the knowledge graph:

nmem tui

nmem tui main nmem tui memory nmem tui thread nmem tui graph

Troubleshooting

"command not found: nmem"

PyPI install: pip install nmem-cli (Python 3.11+)
Run without installing: uvx --from nmem-cli nmem --help
macOS desktop: Settings → Preferences → Developer Tools → Install CLI → then ensure ~/.local/bin is on your PATH
Windows: open a new terminal after app installation

"Cannot connect to server"

Ensure Nowledge Mem is running
Try: nmem --api-url http://127.0.0.1:14242 status
Check for proxy or VPN blocking localhost

Nowledge Mem CLI

On this page

Nowledge Mem CLI

On this page