CLI Commands

Engram CLI works standalone with SQLite and on-disk HNSW indexes. No running server required.

Global flags:

• --config <path> — path to configuration file
• --format <json|text|jsonl> — output format (default json)

engram init

Initializes the ~/.engram/ directory with configuration, database, and prints MCP server setup instructions.

engram init

This command is handled before config loading and does not require an existing engram.toml.

engram server

Starts a Unix socket server to accept JSON requests from the MCP server.

engram server

Listens on ~/.engram/engram.sock (configurable via server.socket_path). Runs background reindexing at reindex_interval_secs interval.

engram store

Saves a new memory record.

engram store \
  --context "Auth module became monolithic, 800 lines" \
  --action "Split into middleware + handler + validator" \
  --result "Each file < 200 lines, tests isolated"

engram store \
  --context "Tokens expired silently" \
  --action "Added validation middleware with structured logging" \
  --result "Auth failures surface immediately with error codes" \
  --memory-type bugfix \
  --tags "auth,middleware" \
  --project api-server

engram search

Searches for relevant records using hybrid search (vector + full-text).

engram search --query "auth middleware architecture"

engram search --query "error handling patterns" --limit 5 --project my-api

engram judge

Rates a memory's quality. Results train the Q-Learning router.

engram judge --memory-id "abc-123-def" --score 0.8

engram status

Shows system status: memory count, index size, pending judgments.

engram status

engram status --format text

engram consolidate

Manages memory consolidation. Three subcommands:

engram consolidate preview

Finds deduplication candidates without making changes.

engram consolidate preview
engram consolidate preview --stale-days 30 --min-score 0.5

engram consolidate analyze

Analyzes candidates with LLM and returns recommendations.

engram consolidate analyze

engram consolidate apply

Applies recommendations: merge, delete, archive.

engram consolidate apply

engram train

Manages self-learning through the trainer.

engram train generate

Runs the trainer to generate insights from memory patterns.

engram train generate

engram train list

Lists active insights.

engram train list

engram train delete

Deletes an insight by ID. Only works for records with type insight.

engram train delete --id "insight-uuid"

engram version

Shows the engram version.

engram version
engram version --format text