Cortex Memory CLI

cortex-mem-cli is the command-line interface for the Cortex Memory system, providing complete terminal access to memory management functionality.

✨ Features

• 🗣️ Session Management: Create and list sessions
• 💬 Message Operations: Add, search, get, and delete messages
• 🔍 Semantic Search: Vector-based search with scope filtering
• 📊 Layer Management: Generate and manage L0/L1 layer files
• 📈 Statistics: View system status and usage statistics
• 🎨 Friendly Output: Colored terminal output with configurable verbosity

🚀 Quick Start

Installation

# Build from source

cd cortex-mem

cargo build --release --bin cortex-mem


# Or run directly

cargo run --bin cortex-mem -- --help

Basic Usage

# Create a new session

./cortex-mem session create tech-discussion --title "Technical Discussion"


# Add a message

./cortex-mem add --thread tech-discussion "How to implement OAuth authentication?"


# Search for relevant content

./cortex-mem search "OAuth" --thread tech-discussion


# View statistics

./cortex-mem stats

📖 Command Reference

Global Options

Option	Short	Default	Description
--config	-c	config.toml	Path to configuration file
--tenant		default	Tenant identifier for memory isolation
--verbose	-v	false	Enable verbose/debug logging

Session Commands

Create Session

cortex-mem session create <thread-id> [--title <title>]


# Examples

cortex-mem session create project-planning --title "Project Planning Discussion"

cortex-mem session create 2024-01-15-review  # Without title

List Sessions

cortex-mem session list

Output displays: thread_id, status, created_at, updated_at

Message Commands

Add Message

cortex-mem add --thread <thread-id> [--role <role>] <content>

# Role options: user, assistant, system (default: user)

cortex-mem add --thread tech-support --role user "I forgot my password, what should I do?"

cortex-mem add --thread tech-support --role assistant "Please visit the password reset page..."

Argument	Short	Default	Description
--thread	-t	(required)	Thread ID for the message
--role	-r	user	Message role: user, assistant, or system
content		(required)	Message content text

Search Messages

cortex-mem search <query> [--thread <thread-id>] [-n <limit>] [-s <min-score>] [--scope <scope>]


# Examples

cortex-mem search "password"

cortex-mem search "OAUTH" -n 5 -s 0.7

cortex-mem search "API" --thread tech-support

Argument	Short	Default	Description
query		(required)	Search query text
--thread	-t	None	Thread ID to search within
--limit	-n	10	Maximum number of results
--min-score	-s	0.4	Minimum relevance score (0.0-1.0)
--scope		session	Search scope: session, user, or agent

List Memories

cortex-mem list [--uri <uri>] [--include-abstracts]


# Examples

cortex-mem list

cortex-mem list --uri cortex://user

cortex-mem list --include-abstracts

Argument	Short	Default	Description
--uri	-u	cortex://session	URI path to list
--include-abstracts		false	Show L0 abstracts in results

Get Memory

cortex-mem get <uri> [--abstract-only] [--overview]


# Examples

cortex-mem get cortex://session/tech-support/timeline/2024/01/15/14_30_00_abc123.md

cortex-mem get cortex://session/tech-support/timeline/2024/01/15/14_30_00_abc123.md --abstract-only

cortex-mem get cortex://session/tech-support/timeline/2024/01/15/14_30_00_abc123.md --overview

Argument	Short	Default	Description
uri		(required)	Memory URI to retrieve
--abstract-only	-a	false	Show L0 abstract (~100 tokens) instead of full content
--overview	-o	false	Show L1 overview (structured summary) instead of full content

Delete Memory

cortex-mem delete <uri>

# Example

cortex-mem delete cortex://session/tech-support/timeline/2024/01/15/14_30_00_abc123.md

Session Close

Close a session and trigger memory extraction, L0/L1 layer generation, and vector indexing.

cortex-mem session close <thread-id>

# Example

cortex-mem session close customer-support

This is the key command for finalizing a conversation — it runs the full processing pipeline:

1. Memory Extraction: LLM analyzes the conversation and extracts structured facts, decisions, and entities.
2. Layer Generation: L0 (abstract) and L1 (overview) files are generated or updated.
3. Vector Indexing: All layers are embedded and indexed in Qdrant for future semantic search.

Layer Commands

Ensure All Layers

Generate missing .abstract.md (L0) and .overview.md (L1) files for all memories.

cortex-mem layers ensure-all

Layer Status

Show L0/L1 file coverage status.

cortex-mem layers status

Regenerate Oversized Abstracts

Regenerate .abstract.md files exceeding the size limit.

cortex-mem layers regenerate-oversized

Statistics

cortex-mem stats

Displays:

• Number of sessions
• Number of user memories
• Number of agent memories
• Total message count
• Data directory path

Tenant Commands

List Tenants

List all available tenant IDs to help you identify the correct --tenant parameter value.

cortex-mem tenant list

Output displays all tenant IDs found in the data directory. Use the desired tenant ID with --tenant <id> for other commands.

⚙️ Configuration

Configuration File

Create a config.toml file with the following structure:

[cortex]

data_dir = "/path/to/cortex-data"  # Optional, has smart defaults



[llm]

api_base_url = "https://api.openai.com/v1"

api_key = "your-api-key"

model_efficient = "gpt-5-mini"

temperature = 0.7

max_tokens = 65536



[embedding]

api_base_url = "https://api.openai.com/v1"

api_key = "your-embedding-api-key"

model_name = "text-embedding-3-small"

batch_size = 10

timeout_secs = 30



[qdrant]

url = "http://localhost:6334"

collection_name = "cortex-mem"

embedding_dim = 1536

timeout_secs = 30

Environment Variables

Configuration can be overridden via environment variables:

export CORTEX_DATA_DIR="/custom/path"

export LLM_API_KEY="your-api-key"

export QDRANT_URL="http://localhost:6333"


cortex-mem session create test

Data Directory Resolution

The data directory is resolved in the following priority order:

1. cortex.data_dir config value
2. CORTEX_DATA_DIR environment variable
3. System app data directory (e.g., %APPDATA%/tars/cortex on Windows)
4. Fallback: ./.cortex in current directory

📝 Complete Workflow Example

# 1. Create a session

cortex-mem session create customer-support --title "Customer Support Session"


# 2. Add conversation messages

cortex-mem add --thread customer-support "What's my order status?"

cortex-mem add --thread customer-support --role assistant "Let me check your order status..."


# 3. Search for relevant information

cortex-mem search "order" --thread customer-support


# 4. View extracted memories

cortex-mem list --uri cortex://user


# 5. Get a specific memory with abstract

cortex-mem get cortex://session/customer-support/timeline/... --abstract-only


# 6. View system statistics

cortex-mem stats


# 7. Generate missing layer files

cortex-mem layers ensure-all

🎨 Output Format

CLI uses color coding for better readability:

• 🔵 Blue: Session IDs and file URIs
• 🟢 Green: Successful operations
• 🟡 Yellow: Warning messages
• 🔴 Red: Error messages
• ⚪ White: General information

🔍 Troubleshooting

Common Issues

Data directory permission error

chmod 755 ./cortex-data

LLM service unavailable

export LLM_API_BASE_URL="https://api.openai.com/v1"

export LLM_API_KEY="your-key"

Vector search failure

# Start Qdrant

docker run -p 6333:6333 qdrant/qdrant


# Configure connection

export QDRANT_URL="http://localhost:6333"

Debug Mode

# Enable verbose logging

cortex-mem --verbose session create debug-test


# View full error stack trace

RUST_BACKTRACE=1 cortex-mem search "test"

🧪 Testing

# Run basic tests (no external services needed)

cargo test -p cortex-mem-cli


# Run all tests including integration tests (requires Qdrant + LLM + Embedding)

CONFIG_PATH=./config.toml TENANT_ID=testcase_user cargo test -p cortex-mem-cli -- --include-ignored

Tests are automatically run in single-threaded mode (configured in .cargo/config.toml) to avoid Qdrant collection creation race conditions.

📚 Related Resources

• Cortex Memory Main Project
• Core Library Documentation
• HTTP API Service
• Architecture Overview

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Create a Pull Request

📄 License

MIT License - see the LICENSE file for details.

---

Built with ❤️ using Rust and the Cortex Memory Core