CLI Reference¶
Complete reference for the nmem command-line interface.
82 commands available.
Tip
Run nmem --help or nmem <command> --help for the latest usage info.
Table of Contents¶
- Memory Operations
nmem remembernmem recallnmem contextnmem todonmem qnmem anmem lastnmem today- Brain Management
nmem brain listnmem brain usenmem brain createnmem brain exportnmem brain importnmem brain deletenmem brain healthnmem brain transplant- Information & Diagnostics
nmem statsnmem statusnmem healthnmem checknmem doctornmem dashboardnmem uinmem graph- Training & Import/Export
nmem trainnmem indexnmem importnmem export- Configuration & Setup
nmem initnmem setupnmem mcp-confignmem promptnmem hooksnmem config presetnmem config tiernmem install-skills- Server & MCP
nmem servenmem mcp- Maintenance
nmem decaynmem consolidatenmem cleanupnmem flush- Project Management
nmem project createnmem project listnmem project shownmem project deletenmem project extend- Advanced Features
nmem shared enablenmem shared disablenmem shared statusnmem shared testnmem shared syncnmem habits listnmem habits shownmem habits clearnmem habits statusnmem version createnmem version listnmem version rollbacknmem version diffnmem telegram statusnmem telegram testnmem telegram backupnmem listnmem migratenmem update- Other
nmem editnmem forgetnmem lifecyclenmem pinnmem shared activatenmem shownmem storage statusnmem storage switchnmem sync activatenmem sync disablenmem sync enablenmem sync statusnmem sync syncnmem sync testnmem unpinnmem watch
Memory Operations¶
nmem remember¶
Store a new memory (type auto-detected if not specified).
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
content |
text | No | `` | (positional argument) |
--tag / -t |
text | No | — | Tags for the memory |
--type / -T |
text | No | — | Memory type: fact, decision, preference, todo, insight, context, instruction, error, workflow, reference (auto-detect... |
--priority / -p |
integer | No | — | Priority 0-10 (0=lowest, 5=normal, 10=critical) |
--expires / -e |
integer | No | — | Days until this memory expires |
--project / -P |
text | No | — | Associate with a project (by name) |
--shared / -S |
boolean | No | False |
Use shared/remote storage for this command |
--force / -f |
boolean | No | False |
Store even if sensitive content is detected or encoding damage is suspected |
--redact / -r |
boolean | No | False |
Auto-redact sensitive content before storing |
--timestamp / --at |
text | No | — | ISO datetime of original event (e.g. '2026-03-02T08:00:00'). Defaults to now. |
--ephemeral |
boolean | No | False |
Session-scoped memory: auto-expires after 24h, never synced |
--stdin |
boolean | No | False |
Read content from stdin even when an argument is also present |
--file |
text | No | — | Read content from a UTF-8 file (bypasses shell pipe encoding entirely) |
--json / -j |
boolean | No | False |
Output as JSON |
A pipe is decoded as UTF-8 when the bytes are valid UTF-8, otherwise with the Windows OEM code page. PowerShell 5.1 pipes ASCII and replaces CJK with "?". CP1252 cannot represent CJK either. Use --file for those.
nmem recall¶
Query memories with intelligent routing (query type auto-detected).
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
query |
text | Yes | — | (positional argument) |
--depth / -d |
integer | No | — | Search depth (0=instant, 1=context, 2=habit, 3=deep) |
--limit / -l |
integer | No | — | Cap matched memories (approximate; maps to max_tokens ~200/memory) |
--max-tokens / -m |
integer | No | 500 |
Max tokens in response |
--min-confidence / -c |
float | No | 0.0 |
Minimum confidence threshold (0.0-1.0) |
--shared / -S |
boolean | No | False |
Use shared/remote storage for this command |
--show-age / -a |
boolean | No | True |
Show memory ages in results |
--show-routing / -R |
boolean | No | False |
Show query routing info |
--json / -j |
boolean | No | False |
Output as JSON |
nmem context¶
Get recent context (for injecting into AI conversations).
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--limit / -l |
integer | No | 10 |
Number of recent memories |
--fresh-only |
boolean | No | False |
Only include memories < 30 days old |
--json / -j |
boolean | No | False |
Output as JSON |
nmem todo¶
Quick shortcut to add a TODO memory.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
task |
text | Yes | — | (positional argument) |
--priority / -p |
integer | No | 5 |
Priority 0-10 (default: 5=normal, 7=high, 10=critical) |
--project / -P |
text | No | — | Associate with a project |
--expires / -e |
integer | No | — | Days until expiry (default: 30) |
--tag / -t |
text | No | — | Tags for the task |
--json / -j |
boolean | No | False |
Output as JSON |
nmem q¶
Quick recall - shortcut for 'nmem recall'.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
query |
text | Yes | — | (positional argument) |
-d |
integer | No | — | — |
nmem a¶
Quick add - shortcut for 'nmem remember' with auto-detect.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
content |
text | Yes | — | (positional argument) |
-p |
integer | No | — | — |
nmem last¶
Show last N memories - quick view of recent activity.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
-n |
integer | No | 5 |
Number of memories to show |
nmem today¶
Show today's memories.
Brain Management¶
nmem brain list¶
List available brains.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--json / -j |
boolean | No | False |
Output as JSON |
nmem brain use¶
Switch to a different brain.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
name |
text | Yes | — | (positional argument) |
This updates config.toml so CLI and MCP servers (without NMEM_BRAIN env var) will use the new brain. MCP servers started with NMEM_BRAIN are pinned to that brain and will NOT be affected by this command.
nmem brain create¶
Create a new brain.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
name |
text | Yes | — | (positional argument) |
--use / -u |
boolean | No | True |
Switch to the new brain after creating |
nmem brain export¶
Export brain to JSON or markdown file.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--output / -o |
text | No | — | Output file path |
--name / -n |
text | No | — | Brain name (default: current) |
--exclude-sensitive / -s |
boolean | No | False |
Exclude memories with sensitive content |
--format / -f |
text | No | json |
Export format: json or markdown |
nmem brain import¶
Import brain from JSON file.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
file |
text | Yes | — | (positional argument) |
--name / -n |
text | No | — | Name for imported brain |
--use / -u |
boolean | No | True |
Switch to imported brain |
--scan |
boolean | No | True |
Scan for sensitive content before importing |
nmem brain delete¶
Delete a brain.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
name |
text | Yes | — | (positional argument) |
--force / -f |
boolean | No | False |
Skip confirmation |
nmem brain health¶
Check brain health (freshness, sensitive content).
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--name / -n |
text | No | — | Brain name (default: current) |
--json / -j |
boolean | No | False |
Output as JSON |
nmem brain transplant¶
Transplant memories from another brain into the current brain.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
source |
text | Yes | — | (positional argument) |
--tag / -t |
text | No | — | Filter by tags |
--type |
text | No | — | Filter by memory types |
--strategy / -s |
text | No | prefer_local |
Conflict resolution strategy |
--json / -j |
boolean | No | False |
Output as JSON |
Information & Diagnostics¶
nmem stats¶
Show brain statistics including freshness and memory type analysis.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--json / -j |
boolean | No | False |
Output as JSON |
nmem status¶
Show current brain status, recent activity, and actionable suggestions.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--json / -j |
boolean | No | False |
Output as JSON |
Unlike 'stats' which shows raw counts, 'status' gives a quick overview of what's happening and what you should do next.
nmem health¶
Show brain health diagnostics with purity score and recommendations.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--json / -j |
boolean | No | False |
Output as JSON |
Analyzes connectivity, diversity, freshness, consolidation, orphan rate, and activation efficiency to produce a composite health grade (A-F) and actionable recommendations.
nmem check¶
Check content for sensitive information without storing.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
content |
text | Yes | — | (positional argument) |
--json / -j |
boolean | No | False |
Output as JSON |
nmem doctor¶
Run system health diagnostics.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--json / -j |
boolean | No | False |
Output as JSON |
--fix |
boolean | No | False |
Auto-fix available issues |
--dev |
boolean | No | False |
Include source checkout and contributor tooling checks |
Checks Python version, config, brain, dependencies, embedding provider, schema version, MCP config, hooks, dedup, surface, and CLI tools.
Use --fix to automatically remediate fixable issues. Use --dev to check contributor setup in a source checkout.
nmem dashboard¶
Show a rich dashboard with brain stats and recent activity.
Displays: - Brain statistics (neurons, synapses, fibers) - Memory types distribution - Freshness analysis - Recent memories
nmem ui¶
Interactive memory browser with rich formatting.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--type / -t |
text | No | — | Filter by memory type |
--search / -s |
text | No | — | Search in memory content |
--limit / -n |
integer | No | 20 |
Number of memories to show |
Browse memories with color-coded types, priorities, and freshness.
nmem graph¶
Visualize neural connections as a tree graph.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
query |
text | No | — | (positional argument) |
--depth / -d |
integer | No | 2 |
Traversal depth (1-3) |
--export / -e |
text | No | — | Export format: svg |
--output / -o |
text | No | — | Output file path (used with --export) |
Shows memories and their relationships (caused_by, leads_to, etc.)
Training & Import/Export¶
nmem train¶
Train a brain from documentation files (markdown).
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
path |
text | No | . |
(positional argument) |
--domain / -d |
text | No | `` | Domain tag (e.g., react, kubernetes) |
--brain / -b |
text | No | `` | Target brain name (default: current) |
--ext / -e |
text | No | — | File extensions (default: .md) |
--no-consolidate |
boolean | No | False |
Skip ENRICH consolidation |
--json / -j |
boolean | No | False |
Output as JSON |
nmem index¶
Index a codebase into neural memory for code-aware recall.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
path |
text | No | . |
(positional argument) |
--ext / -e |
text | No | — | File extensions to index (e.g. .py) |
--status / -s |
boolean | No | False |
Show indexing status instead of scanning |
--json / -j |
boolean | No | False |
Output as JSON |
nmem import¶
Import brain from JSON file.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
input_file |
text | Yes | — | (positional argument) |
--brain / -b |
text | No | — | Target brain name (default: from file) |
--merge / -m |
boolean | No | False |
Merge with existing brain |
--strategy |
text | No | prefer_local |
Conflict resolution: prefer_local, prefer_remote, prefer_recent, prefer_stronger |
nmem export¶
Export brain to JSON file for backup or sharing.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
output |
text | Yes | — | (positional argument) |
--brain / -b |
text | No | — | Brain to export (default: current) |
Configuration & Setup¶
nmem init¶
Set up NeuralMemory in one command.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--force / -f |
boolean | No | False |
Overwrite existing config |
--skip-mcp |
boolean | No | False |
Skip MCP auto-configuration |
--skip-skills |
boolean | No | False |
Skip skills installation |
--wizard / -w |
boolean | No | False |
Interactive setup wizard |
--defaults |
boolean | No | False |
Non-interactive with all defaults |
--full |
boolean | No | False |
Extended setup: embeddings, dedup, maintenance script |
--embeddings |
boolean | No | False |
Set up embedding provider |
--skip-embeddings |
boolean | No | False |
Skip embedding provider setup |
--dedup |
boolean | No | False |
Enable dedup |
Creates config, default brain, auto-configures MCP for Claude Code and Cursor, and installs agent skills.
Use --full for extended setup: auto-detect embeddings, enable dedup, and generate a maintenance script.
nmem setup¶
Set up optional components.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
component |
text | No | `` | (positional argument) |
--ide |
text | No | `` | Target IDE for rules: cursor, windsurf, cline, gemini, agents |
--all |
boolean | No | False |
Generate rules for all supported IDEs |
--force / -f |
boolean | No | False |
Overwrite existing files |
nmem mcp-config¶
Generate MCP server configuration for Claude Code/Cursor.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--with-prompt / -p |
boolean | No | False |
Include system prompt in config |
--compact / -c |
boolean | No | False |
Use compact prompt (if --with-prompt) |
Outputs JSON configuration that can be added to your MCP settings.
nmem prompt¶
Show system prompt for AI tools.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--compact / -c |
boolean | No | False |
Show compact version |
--copy |
boolean | No | False |
Copy to clipboard (requires pyperclip) |
This prompt instructs AI assistants (Claude, GPT, etc.) on when and how to use NeuralMemory for persistent memory across sessions.
nmem hooks¶
Install or manage git hooks for automatic memory capture.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
action |
text | No | install |
(positional argument) |
--path / -p |
text | No | — | Path to git repo (default: current dir) |
nmem config preset¶
Apply a configuration preset or list available presets.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
name |
text | No | `` | (positional argument) |
--list / -l |
boolean | No | False |
List available presets |
--dry-run / -n |
boolean | No | False |
Show changes without applying |
nmem config tier¶
Get or set the MCP tool tier to control token usage.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
name |
text | No | `` | (positional argument) |
--show / -s |
boolean | No | False |
Show current tier |
Tiers control which tools are exposed in tools/list: minimal — 4 core tools (~84% token savings) standard — 8 tools (~69% savings) full — all 63 tools (default)
Hidden tools remain callable — only schema exposure changes.
nmem install-skills¶
Install NeuralMemory skills to ~/.claude/skills/.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--force / -f |
boolean | No | False |
Overwrite existing skills with latest version |
--list / -l |
boolean | No | False |
List available skills without installing |
Skills add AI agent workflows for memory management: memory-intake Structured memory creation from messy notes memory-audit 6-dimension quality review with graded findings memory-evolution Evidence-based optimization from usage patterns
Server & MCP¶
nmem serve¶
Run the NeuralMemory API server.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--host / -h |
text | No | 127.0.0.1 |
Host to bind to |
--port / -p |
integer | No | 8000 |
Port to bind to |
--reload / -r |
boolean | No | False |
Enable auto-reload for development |
nmem mcp¶
Run the MCP (Model Context Protocol) server.
This starts an MCP server over stdio that exposes NeuralMemory tools to Claude Code, Claude Desktop, and other MCP-compatible clients.
Available tools: nmem_remember - Store a memory nmem_recall - Query memories nmem_context - Get recent context nmem_todo - Add a TODO memory nmem_stats - Get brain statistics
Configuration for Claude Code: claude mcp add --scope user neural-memory -- nmem-mcp
Maintenance¶
nmem decay¶
Apply memory decay to simulate forgetting.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--brain / -b |
text | No | — | Brain to apply decay to |
--dry-run / -n |
boolean | No | False |
Preview changes without applying |
--prune / -p |
float | No | 0.01 |
Prune below this activation level |
Memories that haven't been accessed recently will have their activation levels reduced following the Ebbinghaus forgetting curve.
nmem consolidate¶
Consolidate brain memories by pruning, merging, or summarizing.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--brain / -b |
text | No | — | Brain to consolidate |
--strategy / -s |
text | No | all |
Consolidation strategy. Valid values: prune, merge, summarize, mature, infer, enrich, dream, learn_habits, dedup, sem... |
--dry-run / -n |
boolean | No | False |
Preview changes without applying |
--prune-threshold |
float | No | 0.05 |
Weight threshold for pruning synapses |
--merge-overlap |
float | No | 0.5 |
Jaccard overlap threshold for merging fibers |
--min-inactive-days |
float | No | 7.0 |
Minimum inactive days before pruning |
Runs one or more consolidation passes on the current (or specified) brain. Use --strategy to pick a specific pass, or omit it to run everything.
Strategies: prune - Remove weak synapses and orphan neurons merge - Combine overlapping fibers summarize - Create concept neurons for topic clusters mature - Advance episodic memories to semantic stage infer - Add inferred synapses from co-activation patterns enrich - Enrich neurons with extracted metadata dream - Generate synthetic bridging memories learn_habits - Extract recurring workflow patterns dedup - Merge near-duplicate memories semantic_link - Add cross-domain semantic connections compress - Compress old low-activation fibers all - Run all strategies in dependency order (default)
nmem cleanup¶
Clean up expired or old memories.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--expired / -e |
boolean | No | True |
Only clean up expired memories |
--type / -T |
text | No | — | Only clean up specific memory type |
--dry-run / -n |
boolean | No | False |
Show what would be deleted without deleting |
--force / -f |
boolean | No | False |
Skip confirmation |
--json / -j |
boolean | No | False |
Output as JSON |
nmem flush¶
Emergency flush: capture memories before context is lost.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--transcript / -t |
text | No | — | Path to JSONL transcript file |
text |
text | No | — | (positional argument) |
--json / -j |
boolean | No | False |
Output as JSON |
Aggressively detects and saves all memorable content with lowered confidence threshold. Designed for pre-compaction or session-end scenarios.
Project Management¶
nmem project create¶
Create a new project for organizing memories.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
name |
text | Yes | — | (positional argument) |
--description / -d |
text | No | — | Project description |
--duration / -D |
integer | No | — | Duration in days (creates end date) |
--tag / -t |
text | No | — | Project tags |
--priority / -p |
float | No | 1.0 |
Project priority (default: 1.0) |
--json / -j |
boolean | No | False |
Output as JSON |
Projects group related memories and enable time-bounded retrieval.
nmem project list¶
List all projects.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--active / -a |
boolean | No | False |
Show only active projects |
--json / -j |
boolean | No | False |
Output as JSON |
nmem project show¶
Show project details and its memories.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
name |
text | Yes | — | (positional argument) |
--json / -j |
boolean | No | False |
Output as JSON |
nmem project delete¶
Delete a project (memories are preserved but unlinked).
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
name |
text | Yes | — | (positional argument) |
--force / -f |
boolean | No | False |
Skip confirmation |
nmem project extend¶
Extend a project's deadline.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
name |
text | Yes | — | (positional argument) |
days |
integer | Yes | — | (positional argument) |
--json / -j |
boolean | No | False |
Output as JSON |
Advanced Features¶
nmem shared enable¶
Enable shared mode to connect to a remote NeuralMemory server.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
server_url |
text | Yes | — | (positional argument) |
--api-key / -k |
text | No | — | API key for authentication |
--timeout / -t |
float | No | 30.0 |
Request timeout in seconds |
When shared mode is enabled, all memory operations (remember, recall, etc.) will use the remote server instead of local storage.
nmem shared disable¶
Disable shared mode and use local storage.
nmem shared status¶
Show shared mode status and configuration.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--json / -j |
boolean | No | False |
Output as JSON |
nmem shared test¶
Test connection to the shared server.
nmem shared sync¶
Manually sync local brain with remote server.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--direction / -d |
text | No | both |
Sync direction: push, pull, or both |
--json / -j |
boolean | No | False |
Output as JSON |
Directions: push - Upload local brain to server pull - Download brain from server to local both - Full bidirectional sync (default)
nmem habits list¶
List learned workflow habits.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--json / -j |
boolean | No | False |
Output as JSON |
Shows all habits discovered through action sequence mining, including step sequences, frequencies, and confidence scores.
nmem habits show¶
Show details of a specific learned habit.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
name |
text | Yes | — | (positional argument) |
--json / -j |
boolean | No | False |
Output as JSON |
nmem habits clear¶
Clear all learned habits.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--force / -f |
boolean | No | False |
Skip confirmation |
Removes all WORKFLOW fibers with _habit_pattern metadata. This does not affect action event history.
nmem habits status¶
Show progress toward habit detection.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--json / -j |
boolean | No | False |
Output as JSON |
Displays emerging action patterns that haven't yet reached the frequency threshold to become learned habits. Helps you understand how close your workflows are to being recognized.
nmem version create¶
Create a version snapshot of the current brain state.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
name |
text | Yes | — | (positional argument) |
--description / -d |
text | No | `` | Description |
--json / -j |
boolean | No | False |
Output as JSON |
nmem version list¶
List brain versions.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--limit / -l |
integer | No | 20 |
Max versions |
--json / -j |
boolean | No | False |
Output as JSON |
nmem version rollback¶
Rollback brain to a previous version.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
version_id |
text | Yes | — | (positional argument) |
--json / -j |
boolean | No | False |
Output as JSON |
nmem version diff¶
Compare two brain versions.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
from_version |
text | Yes | — | (positional argument) |
to_version |
text | Yes | — | (positional argument) |
--json / -j |
boolean | No | False |
Output as JSON |
nmem telegram status¶
Show Telegram integration status.
nmem telegram test¶
Send a test message to verify configuration.
nmem telegram backup¶
Send brain database file as backup to Telegram.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--brain / -b |
text | No | — | Brain name (default: active brain) |
nmem list¶
List memories with filtering by type, priority, project, and status.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--type / -T |
text | No | — | Filter by memory type (fact, decision, todo, etc.) |
--min-priority / -p |
integer | No | — | Minimum priority (0-10) |
--project / -P |
text | No | — | Filter by project name |
--expired / -e |
boolean | No | False |
Show only expired memories |
--include-expired |
boolean | No | False |
Include expired memories in results |
--limit / -l |
integer | No | 20 |
Maximum number of results |
--full |
boolean | No | False |
Return full content instead of a 100-char summary |
--json / -j |
boolean | No | False |
Output as JSON |
Content is summarised to 100 characters by default; pass --full (or use
nmem show <id>) when the complete text matters.
Memory types: fact, decision, preference, todo, insight, context, instruction, error, workflow, reference
nmem migrate¶
Migrate brain data between storage backends.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
target |
text | Yes | — | (positional argument) |
--brain / -b |
text | No | — | Specific brain to migrate (default: current) |
--pg-host |
text | No | localhost |
PostgreSQL host |
--pg-port |
integer | No | 5432 |
PostgreSQL port |
--pg-database |
text | No | neuralmemory |
PostgreSQL database name |
--pg-user |
text | No | postgres |
PostgreSQL user |
--pg-password |
text | No | `` | PostgreSQL password (or use NEURAL_MEMORY_POSTGRES_PASSWORD env) |
nmem update¶
Update neural-memory to the latest version.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--force / -f |
boolean | No | False |
Force update even if already latest |
--check / -c |
boolean | No | False |
Only check for updates, don't install |
Automatically detects install method (pip or git source) and updates accordingly.
Other¶
nmem edit¶
Edit a memory's type, content, priority, or tier.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
memory_id |
text | Yes | — | (positional argument) |
--type / -T |
text | No | — | New memory type |
--content / -c |
text | No | — | New content for the anchor neuron |
--priority / -p |
integer | No | — | New priority 0-10 |
--tier |
text | No | — | New tier: hot, warm, or cold |
--shared / -S |
boolean | No | False |
Use shared/remote storage |
--json / -j |
boolean | No | False |
Output as JSON |
nmem forget¶
Soft- or hard-delete a memory by fiber ID (or neuron ID with --hard).
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
memory_id |
text | Yes | — | (positional argument) |
--hard |
boolean | No | False |
Permanent deletion (cascade cleanup). Default is soft delete (expire now). |
--reason / -r |
text | No | `` | Reason for forgetting (logged for audit) |
--force / -f |
boolean | No | False |
Confirm permanent deletion when using --hard |
--shared / -S |
boolean | No | False |
Use shared/remote storage |
--json / -j |
boolean | No | False |
Output as JSON |
Soft delete sets expires_at=now; consolidation removes the fiber later. Hard delete drops the fiber + typed_memory immediately (CASCADE handles fiber_neurons) and requires --force, mirroring the confirmation gate on nmem_cleanup and on the MCP tools.
nmem lifecycle¶
Manage memory lifecycle states.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
action |
text | No | status |
(positional argument) |
neuron_id |
text | No | — | (positional argument) |
--brain / -b |
text | No | — | Brain name |
View lifecycle distribution or freeze/thaw/recover individual memories.
nmem pin¶
Pin a fiber as permanent KB (skips decay/prune; promotes tier to HOT).
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
fiber_id |
text | Yes | — | (positional argument) |
--shared / -S |
boolean | No | False |
Use shared/remote storage |
--limit / -l |
integer | No | 50 |
When fiber_id='list', cap number of results |
--json / -j |
boolean | No | False |
Output as JSON |
Use 'list' as the argument to list currently-pinned fibers.
nmem shared activate¶
Activate a NeuralMemory Pro license key.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--key / -k |
text | Yes | — | License key (NM-PRO-XXXX-XXXX-XXXX) |
nmem show¶
Show full content + metadata for a memory by ID.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
memory_id |
text | Yes | — | (positional argument) |
--shared / -S |
boolean | No | False |
Use shared/remote storage |
--json / -j |
boolean | No | False |
Output as JSON |
Works for typed fibers, untyped fibers, and bare neurons. Useful for debugging when recall returns an ID that other commands can't resolve.
nmem storage status¶
Show current storage backend status.
Displays which backend is active, Pro license status, and whether data files exist for each backend.
nmem storage switch¶
Switch active storage backend.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
backend |
text | Yes | — | (positional argument) |
Switches config.toml to use the specified backend. Data must already exist for the target backend (run migrate first).
nmem sync activate¶
Activate a NeuralMemory Pro license key.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--key / -k |
text | Yes | — | License key (NM-PRO-XXXX-XXXX-XXXX) |
nmem sync disable¶
Disable shared mode and use local storage.
nmem sync enable¶
Enable shared mode to connect to a remote NeuralMemory server.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
server_url |
text | Yes | — | (positional argument) |
--api-key / -k |
text | No | — | API key for authentication |
--timeout / -t |
float | No | 30.0 |
Request timeout in seconds |
When shared mode is enabled, all memory operations (remember, recall, etc.) will use the remote server instead of local storage.
nmem sync status¶
Show shared mode status and configuration.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--json / -j |
boolean | No | False |
Output as JSON |
nmem sync sync¶
Manually sync local brain with remote server.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
--direction / -d |
text | No | both |
Sync direction: push, pull, or both |
--json / -j |
boolean | No | False |
Output as JSON |
Directions: push - Upload local brain to server pull - Download brain from server to local both - Full bidirectional sync (default)
nmem sync test¶
Test connection to the shared server.
nmem unpin¶
Unpin a fiber (removes grounding; allows decay/prune again).
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
fiber_id |
text | Yes | — | (positional argument) |
--shared / -S |
boolean | No | False |
Use shared/remote storage |
--json / -j |
boolean | No | False |
Output as JSON |
nmem watch¶
Watch a directory and auto-ingest files into memory.
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
directory |
text | No | `` | (positional argument) |
--action / -a |
text | No | scan |
Action: scan, start, stop, status |
--json / -j |
boolean | No | False |
Output as JSON |
Auto-generated by scripts/gen_cli_docs.py from Typer app introspection — 82 commands.