CLI Commands Reference

Complete guide to every truenex-mem command, parameter, and example.

Quick navigation

Setup & Diagnostics
Manual Memory
Indexing & Search
Import / Export
Git Sync
Agent Integration
Global Store
Agent Manifest
Task Pipeline
Orchestration
License
Utility

Setup & Diagnostics

Safe

truenex-mem init

Prepares the hidden .truenex-memory/ folder in the current directory. Run once per project.

truenex-mem init

truenex-mem doctor

Quick diagnostic: shows if the database exists, how many documents/chunks you have, and which vector backend is active.

truenex-mem doctor
truenex-mem doctor --privacy

truenex-mem migrate

Manages database schema migrations when upgrading to a new version.

Sub-command	What it does	Example
`status`	Show current and latest schema version	`migrate status`
`apply`	Apply pending migrations (auto-backup first)	`migrate apply`
`backup-list`	List available backups	`migrate backup-list`
`restore`	Restore a backup	`migrate restore backup_20250602.db`

Manual Memory

Safe

truenex-mem add

Writes a manual memory node into the local project database.

truenex-mem add "We use FastAPI + JWT for auth" --type decision

Types: note, decision, issue, pattern

truenex-mem list

Lists all manual memory nodes you added.

truenex-mem list
truenex-mem list --status obsolete
truenex-mem list --json

truenex-mem status

Changes the lifecycle status of a memory node.

truenex-mem status set mem_abc123 obsolete

Statuses: active, obsolete, superseded, conflicting, unverified

Indexing & Search

Safe

truenex-mem index

Reads project files, splits them into chunks, and stores them for semantic search.

truenex-mem index # index entire project
truenex-mem index src/main.py # index single file
truenex-mem index ./docs # index single folder

truenex-mem search

Searches indexed documents using semantic + text search.

truenex-mem search "how does auth work"
truenex-mem search "JWT token" --top-k 10
truenex-mem search "refactor" --include-inactive

Known issue: search currently finds only indexed documents, not manual memories added with add.

truenex-mem logs

Shows recent search queries and their results.

truenex-mem logs
truenex-mem logs -n 5
truenex-mem logs --json

truenex-mem trace

Shows full details of a single search trace.

truenex-mem trace show ret_abc123

Import / Export

Safe

truenex-mem export

Dumps the entire local database to a JSON file (backup).

truenex-mem export --output backup.json

truenex-mem import

Restores data from a previously exported JSON file.

truenex-mem import backup.json

Git Sync PRO

Safe

Synchronize your memory database across multiple PCs using any Git remote. Your data stays private — exported as JSON, compressed with gzip, and pushed to your own private repository. A rare feature in the local AI memory space.

truenex-mem git init

Initializes the Git Bridge sync directory in ~/.truenex-memory/sync/.

truenex-mem git init

truenex-mem git remote add

Links your sync directory to a private Git remote (SSH URL recommended).

truenex-mem git remote add origin [email protected]:YOUR_USER/YOUR_REPO.git

truenex-mem git push

Exports the local database to JSON, compresses it with gzip, commits and pushes to the remote.

truenex-mem git push

truenex-mem git pull

Pulls the latest memory data from the remote, decompresses it, and imports it into the local database. Automatically repairs missing embeddings and UUIDs.

truenex-mem git pull

truenex-mem git remote remove

Removes the configured remote.

truenex-mem git remote remove origin

Why Git Sync is special: Most local AI memory tools trap your data on a single device. Truenex Memory Pro lets you own your sync infrastructure — any Git provider, private repo, no cloud lock-in. With automatic gzip compression (118 MB → ~22 MB), embedding auto-repair after import, and intelligent upsert (no duplicates), it's one of the few solutions that truly respects multi-device workflows without compromising privacy.

For a complete setup walkthrough, see the Git Bridge Setup Guide.

Agent Integration

truenex-mem adapter

Prints instructions to copy into your AI agent config so it knows how to use Truenex Memory.

truenex-mem adapter claude-md
truenex-mem adapter agents-md

truenex-mem mcp

Blocking

Starts a stdio server speaking the MCP (Model Context Protocol). This is how Claude Code, Codex, and Cursor talk to Truenex Memory as an external tool. The process stays alive until you press Ctrl+C.

truenex-mem mcp

truenex-mem serve

Blocking

Starts an HTTP API server (default 127.0.0.1:8000) for the Truenex Memory Desktop GUI. Stays alive until Ctrl+C.

truenex-mem serve
truenex-mem serve --port 9000

Bug: requires httpx which is not included in the current PyPI package.

Global Store

Safe

The global store lives in ~/.truenex-memory/ and holds data for all your projects.

Sub-command	What it does	Example
`status`	Global store status	`global status`
`discover`	Finds projects from agent clients	`global discover`
`refresh`	Incremental refresh from catalog	`global refresh`
`context`	Read-only context for a project	`global context my-project`
`search`	Search global store without mutating logs	`global search "query"`
`sources`	Review and confirm source catalog	`global sources`

Agent Manifest

Safe

Manage the external JSON manifest that controls which AI agent directories Truenex Memory scans. No hardcoded paths — fully user-configurable.

truenex-mem agent list

Shows all agents configured in the manifest and their scan roots.

truenex-mem agent list

truenex-mem agent add

Adds a new agent to the discovery manifest. The manifest is stored at ~/.truenex-memory/agent_manifest.json.

truenex-mem agent add windsurf --dir .windsurf --subdir sessions

Creates a new agent entry. To add an extra root to an existing agent, edit the JSON manually.

truenex-mem agent remove

Removes an agent from the manifest.

truenex-mem agent remove windsurf

Default agents: Codex, Claude, Kimi, Cursor, OpenClaw, Aider, Antigravity, Gemini. The manifest is created automatically with embedded defaults if missing. Edit the JSON directly for advanced changes (multiple roots per agent, custom labels).

Task Pipeline

Safe

Tracks adaptive tasks executed by AI agents, with human judgment and calibration stats.

Sub-command	What it does	Example
`open "TITLE"`	Open a new task record	`task open "Refactor auth"`
`close ID`	Close a task with human judgment	`task close task_abc123`
`list`	List recent tasks	`task list`
`show ID`	Show task details with steps	`task show task_abc123`
`calibration`	Show calibration statistics	`task calibration`

Orchestration

Advanced

Recursive multi-agent loop: multiple AI agents work in sequence, converging toward a solution.

Sub-command	What it does	Example
`run FILE.json`	Execute recursive loop from JSON config	`orchestrate run config.json`
`converge-check A B`	Check if two rounds are byte-identical	`orchestrate converge-check r1.json r2.json`

License

Safe

Manage your Truenex Memory Pro license.

Sub-command	What it does	Example
`status`	Show active license	`license status`
`activate KEY`	Activate a Pro license	`license activate trxn-pro-XXXX`
`deactivate`	Remove local license file	`license deactivate --yes`
`require TIER`	Check if current tier meets minimum	`license require pro`

Utility

Safe

Command	What it does	Example
`version`	Print version string	`version`
`version-info`	Print all component versions as JSON	`version-info`
`update check`	Check for updates (no data sent)	`update check`

Typical workflow

# 1. Setup
cd my-project
truenex-mem init

# 2. Annotate decisions
truenex-mem add "Use PostgreSQL, not MySQL" --type decision

# 3. Index code
truenex-mem index

# 4. Search
truenex-mem search "database choice"

# 5. Check health
truenex-mem doctor

# 6. Activate Pro license
truenex-mem license activate trxn-pro-XXXXXXXXXXXXXXXX

# 7. Sync to another PC (Pro)
truenex-mem git push # on PC with new data
truenex-mem git pull # on the other PC