CLI Reference

CLI Reference

Cortex provides a comprehensive CLI for managing memory primitives, running the MCP server, and performing maintenance operations.

Global Flags

These flags are available on all commands:

Flag	Description
--config	Path to config file (default: ~/.cortex/config.yaml)
--namespace	Namespace for operations (default: default)
--verbose	Enable verbose output
--json	Output in JSON format

---

Server

cortex serve

Start the MCP server.

cortex serve [flags]

Flags:

Flag	Description	Default
--transport	Transport mode: stdio or sse	stdio
--port	Port for SSE transport	9810
--namespace	Restrict to a single namespace	(all)

Examples:

# Start with stdio (default for Claude Desktop)
cortex serve

# Start with SSE for web clients
cortex serve --transport sse --port 9810

# Restrict to a specific namespace
cortex serve --namespace my-project

---

Knowledge Store

cortex knowledge ingest

Ingest a single document.

cortex knowledge ingest [flags]

Flags:

Flag	Description	Required
--collection	Target collection name	Yes
--title	Document title	Yes
--file	Path to file	Yes
--chunk-strategy	Chunking: fixed, sentence, paragraph, semantic	No
--chunk-max-tokens	Maximum tokens per chunk	No
--chunk-overlap	Token overlap between chunks	No
--metadata	JSON metadata to attach	No

Examples:

# Basic ingestion
cortex knowledge ingest \
  --collection docs \
  --title "User Guide" \
  --file user-guide.md

# With chunking options
cortex knowledge ingest \
  --collection docs \
  --title "API Reference" \
  --file api.md \
  --chunk-strategy paragraph \
  --chunk-max-tokens 1024

# With metadata
cortex knowledge ingest \
  --collection docs \
  --title "FAQ" \
  --file faq.md \
  --metadata '{"category": "support", "version": "2.0"}'

cortex knowledge ingest-dir

Bulk ingest files from a directory.

cortex knowledge ingest-dir [flags]

Flags:

Flag	Description	Required
--collection	Target collection name	Yes
--dir	Directory path	Yes
--pattern	Glob pattern for files	No
--recursive	Include subdirectories	No

Examples:

# Ingest all markdown files
cortex knowledge ingest-dir \
  --collection docs \
  --dir ./documentation \
  --pattern "*.md"

# Recursive with multiple patterns
cortex knowledge ingest-dir \
  --collection code \
  --dir ./src \
  --pattern "*.go" \
  --recursive

cortex knowledge search

Search the knowledge store.

cortex knowledge search <query> [flags]

Flags:

Flag	Description	Default
--collection	Limit to collection	(all)
--mode	Search mode: vector, fts, hybrid	hybrid
--limit	Maximum results	10
--threshold	Minimum similarity score	0.0

Examples:

# Basic search
cortex knowledge search "how to configure authentication"

# Hybrid search in specific collection
cortex knowledge search "error handling" \
  --collection docs \
  --mode hybrid \
  --limit 5

cortex knowledge collections

List collections.

cortex knowledge collections [flags]

cortex knowledge create-collection

Create a new collection.

cortex knowledge create-collection [flags]

Flags:

Flag	Description	Required
--name	Collection name	Yes
--description	Collection description	No

cortex knowledge stats

Show knowledge store statistics.

cortex knowledge stats [flags]

---

Conversation Memory

cortex conversation append

Add a message to a conversation.

cortex conversation append [flags]

Flags:

Flag	Description	Required
--thread-id	Conversation thread ID	Yes
--role	Message role: user, assistant, system, tool	Yes
--content	Message content	Yes
--metadata	JSON metadata	No

Examples:

cortex conversation append \
  --thread-id support-123 \
  --role user \
  --content "I need help with my order"

cortex conversation history

Retrieve conversation history.

cortex conversation history [flags]

Flags:

Flag	Description	Default
--thread-id	Conversation thread ID	Required
--limit	Maximum messages	50
--before	Messages before timestamp	(none)
--after	Messages after timestamp	(none)

cortex conversation search

Search across conversations.

cortex conversation search <query> [flags]

Flags:

Flag	Description	Default
--thread-id	Limit to thread	(all)
--limit	Maximum results	10

cortex conversation list

List conversation threads.

cortex conversation list [flags]

cortex conversation summarize

Summarize and compress conversation history.

cortex conversation summarize [flags]

Flags:

Flag	Description	Required
--thread-id	Thread to summarize	Yes
--keep-recent	Messages to keep uncompressed	No

cortex conversation clear

Delete conversation history.

cortex conversation clear [flags]

Flags:

Flag	Description	Required
--thread-id	Thread to clear	Yes

---

Workflow Context

cortex context get

Retrieve a value.

cortex context get <key> [flags]

Flags:

Flag	Description
--run-id	Scope to specific run

cortex context set

Store a value.

cortex context set <key> <value> [flags]

Flags:

Flag	Description
--ttl	Time-to-live (e.g., 24h, 7d)
--run-id	Scope to specific run

Examples:

# Simple set
cortex context set "config/debug" "true"

# JSON value with TTL
cortex context set "cache/user-123" '{"name": "Alice"}' --ttl 1h

cortex context merge

Merge values with strategy.

cortex context merge <key> <value> [flags]

Flags:

Flag	Description	Default
--strategy	Merge strategy: replace, merge_shallow, merge_deep, append	replace

cortex context list

List keys.

cortex context list [flags]

Flags:

Flag	Description
--prefix	Filter by key prefix
--run-id	Scope to specific run

cortex context history

View version history.

cortex context history <key> [flags]

cortex context delete

Delete a key.

cortex context delete <key> [flags]

cortex context cleanup

Clean up expired or old context data.

cortex context cleanup [flags]

Flags:

Flag	Description
--expired-ttl	Remove expired TTL values
--old-runs	Remove old run-scoped values
--dry-run	Show what would be deleted

---

Entity Memory

cortex entity list

List entities.

cortex entity list [flags]

Flags:

Flag	Description
--type	Filter by type: person, organization, location, concept, product, event
--sort	Sort by: name, mention_count, created_at
--limit	Maximum results

cortex entity get

Get entity details.

cortex entity get <id>

cortex entity search

Semantic search for entities.

cortex entity search <query> [flags]

cortex entity create

Create a new entity.

cortex entity create [flags]

Flags:

Flag	Description	Required
--name	Entity name	Yes
--type	Entity type	Yes
--description	Description	No
--metadata	JSON metadata	No

cortex entity add-alias

Add an alias to an entity.

cortex entity add-alias <id> [flags]

Flags:

Flag	Description	Required
--alias	Alias to add	Yes

cortex entity add-relationship

Create a relationship between entities.

cortex entity add-relationship <source-id> <target-id> [flags]

Flags:

Flag	Description	Required
--type	Relationship type (e.g., works_at, knows, part_of)	Yes
--metadata	JSON metadata	No

cortex entity relationships

Get entity relationships.

cortex entity relationships <id> [flags]

Flags:

Flag	Description	Default
--direction	incoming, outgoing, or both	both
--type	Filter by relationship type	(all)

cortex entity merge

Merge duplicate entities.

cortex entity merge <keep-id> <remove-id>

cortex entity queue-stats

Show entity extraction queue statistics.

cortex entity queue-stats

---

Maintenance

cortex gc

Run garbage collection.

cortex gc [flags]

Flags:

Flag	Description
--all	Run all cleanup tasks
--dry-run	Show what would be deleted

cortex backup

Create a database backup.

cortex backup [flags]

Flags:

Flag	Description	Required
--output	Output file path	Yes

cortex export

Export namespace data to JSON.

cortex export [flags]

Flags:

Flag	Description	Required
--namespace	Namespace to export	Yes
--output	Output file path	Yes

cortex namespace stats

Show namespace statistics.

cortex namespace stats [flags]

cortex namespace delete

Delete a namespace and all its data.

cortex namespace delete <namespace> [flags]

Flags:

Flag	Description
--force	Skip confirmation prompt

Caution

This permanently deletes all data in the namespace. Use with care.

---

Terminal UI

cortex tui

Launch the interactive terminal UI.

cortex tui [flags]

Flags:

Flag	Description
--namespace	Default namespace to browse

Navigation:

Key	Action
1-5	Switch sections
j/k	Move up/down
Enter	Select item
/	Search
q	Quit