CLI Reference

Complete reference for all Cerememory CLI commands and flags.

Global Flags

Flag	Type	Default	Description
`--data-dir`	path	`./data`	Data directory for persistent storage
`--config`	path	None	Path to TOML configuration file

serve

Start the HTTP server and, optionally, the gRPC server.

bash

cerememory serve [OPTIONS]

Flag	Type	Default	Description
`--port`	u16	`8420`	HTTP port
`--grpc-port`	u16	None	Enable gRPC on this port

Example: Start HTTP and gRPC together

bash

cerememory serve --port 8420 --grpc-port 8421 --config ./cerememory.toml

The server provides:

GET /health and GET /readiness
Optional /metrics when http.metrics_enabled = true
Request IDs, auth, and rate limiting according to config
Background decay ticks on the configured interval

consolidate

Consolidate mature episodic memories into semantic memory.

bash

cerememory consolidate [OPTIONS]

Flag	Type	Default	Description
`--strategy`	string	`incremental`	`incremental`, `full`, or `selective`
`--min-age-hours`	u32	`0`	Minimum record age before consolidation
`--min-access-count`	u32	`0`	Minimum access count before consolidation
`--dry-run`	bool	`false`	Preview work without mutating data

Example: Preview a selective consolidation run

bash

cerememory consolidate \
  --strategy selective \
  --min-age-hours 24 \
  --min-access-count 3 \
  --dry-run

set-mode

Change the recall mode used by stateful operations.

bash

cerememory set-mode <MODE> [OPTIONS]

Flag	Type	Default	Description
`<MODE>`	string	--	Required. `human` or `perfect`
`--scope`	string	None	Optional comma-separated store filter

Example: Set perfect mode for semantic memory

bash

cerememory set-mode perfect --scope semantic

store

Store a new text memory record.

bash

cerememory store <TEXT> [OPTIONS]

Flag	Type	Default	Description
`<TEXT>`	string	--	Required. Text content to store
`--store`	string	`episodic`	Target store
`--embedding`	string	None	Comma-separated embedding vector
`--meta-json`	JSON string	None	Structured MetaMemory with intent, rationale, evidence, and decision context

Example: Store a semantic memory

bash

cerememory store "The user prefers dark mode" --store semantic

store-raw

Store a verbatim raw journal entry.

bash

cerememory store-raw <TEXT> [OPTIONS]

Flag	Type	Default	Description
`<TEXT>`	string	--	Required. Text content to preserve
`--session-id`	string	--	Required. Session identifier
`--topic-id`	string	None	Topic identifier for dream grouping
`--source`	string	`conversation`	`conversation`, `tool_io`, `scratchpad`, `summary`, or `imported`
`--speaker`	string	`user`	`user`, `assistant`, `system`, or `tool`
`--visibility`	string	`normal`	`normal`, `private_scratch`, or `sealed`
`--secrecy-level`	string	`public`	`public`, `sensitive`, or `secret`
`--meta-json`	JSON string	None	Structured MetaMemory describing why the raw entry is preserved

Example: Store a conversation turn

bash

cerememory store-raw "I prefer using Neovim for all my coding" \
  --session-id sess-001 \
  --source conversation \
  --speaker user

recall

Recall memories by text query.

bash

cerememory recall <QUERY> [OPTIONS]

Flag	Type	Default	Description
`<QUERY>`	string	--	Required. Text query
`--limit`	u32	`10`	Maximum number of results
`--mode`	string	`human`	`human` or `perfect`

Example: Recall with perfect mode

bash

cerememory recall "user preferences" --limit 5 --mode perfect

recall-raw

Query the raw journal for verbatim entries.

bash

cerememory recall-raw [QUERY] [OPTIONS]

Flag	Type	Default	Description
`[QUERY]`	string	None	Optional full-text search query
`--session-id`	string	None	Filter by session
`--limit`	u32	`10`	Maximum number of results
`--include-private-scratch`	bool	`false`	Include `private_scratch` entries
`--include-sealed`	bool	`false`	Include `sealed` entries
`--secrecy-levels`	string	All	Comma-separated `public`, `sensitive`, `secret`

Example: Search raw journal by session

bash

cerememory recall-raw "editor preference" --session-id sess-001

inspect

Inspect a specific record as pretty-printed JSON.

bash

cerememory inspect <RECORD_ID>

Flag	Type	Description
`<RECORD_ID>`	UUID	Required. Record UUID

The output includes fidelity state, emotion vector, associations, metadata, meta-memory, and version.

stats

Show system-wide statistics.

bash

cerememory stats

The response includes total records, per-store counts, total associations, average fidelity, background decay status, and evolution_metrics when available.

decay-tick

Run a manual decay cycle.

bash

cerememory decay-tick [OPTIONS]

Flag	Type	Default	Description
`--duration`	u32	`3600`	Simulated duration in seconds

Example: Advance decay by two hours

bash

cerememory decay-tick --duration 7200

dream-tick

Run dream processing to summarize raw journal entries into curated episodic and semantic memories.

bash

cerememory dream-tick [OPTIONS]

Flag	Type	Default	Description
`--session-id`	string	None	Process only entries from this session
`--dry-run`	bool	`false`	Preview without creating records
`--max-groups`	u32	`10`	Maximum topic groups to process per call
`--include-private-scratch`	bool	`false`	Include `private_scratch` entries
`--include-sealed`	bool	`false`	Include `sealed` entries
`--promote-semantic`	bool	`true`	Promote factual content to the semantic store
`--secrecy-levels`	string	All	Comma-separated `public`, `sensitive`, `secret`

Example: Dream-process a specific session

bash

cerememory dream-tick --session-id sess-001 --dry-run

forget

Permanently delete a memory record.

bash

cerememory forget <RECORD_ID> [OPTIONS]

Flag	Type	Default	Description
`<RECORD_ID>`	UUID	--	Required. Target record
`--cascade`	bool	`false`	Also delete associated records
`--confirm`	bool	`false`	Required confirmation flag

export

Export records to a CMA archive file.

bash

cerememory export [OPTIONS]

Flag	Type	Default	Description
`--output`	path	`./backup.cma`	Output file path
`--format`	string	`cma`	Archive format (`cma` or `jsonl`; the latter is an alias)
`--stores`	string	None	Comma-separated store filter
`--include-raw-journal`	bool	`false`	Include raw journal entries in the archive
`--encrypt`	bool	`false`	Encrypt the archive
`--encryption-key`	string	None	Archive passphrase
`--encryption-key-stdin`	bool	`false`	Read the archive passphrase from stdin

Example: Export selected stores with encryption

bash

cerememory export \
  --output ./memories-backup.cma \
  --stores episodic,semantic \
  --encrypt \
  --encryption-key-stdin

import

Import records from a CMA archive file.

bash

cerememory import <PATH> [OPTIONS]

Flag	Type	Default	Description
`<PATH>`	path	--	Required. CMA archive path
`--strategy`	string	`merge`	`merge` or `replace`
`--decryption-key`	string	None	Decryption passphrase for encrypted archives
`--decryption-key-stdin`	bool	`false`	Read the decryption passphrase from stdin
`--conflict-resolution`	string	`keep_newer`	`keep_existing`, `keep_imported`, or `keep_newer`

Example: Import an encrypted archive

bash

cerememory import ./memories-backup.cma \
  --decryption-key-stdin \
  --conflict-resolution keep_newer

Rewrite existing plaintext persistent redb payloads using the configured store encryption passphrase. Existing plaintext records remain readable until they are migrated, so the engine can keep running during migration.

bash

cerememory migrate-store-encryption --confirm

Flag	Type	Default	Description
`--confirm`	bool	`false`	Required confirmation flag for non-interactive use

The command requires security.store_encryption_passphrase (or the CEREMEMORY_SECURITY__STORE_ENCRYPTION_PASSPHRASE env var) to be set. It reports per-store record counts: total, migrated, already_encrypted across raw_journal, episodic, semantic, procedural, emotional, and the vector index.

audit-verify

Verify the tamper-evident audit log hash chain. Useful for incident response and routine integrity checks.

bash

cerememory audit-verify [--path <PATH>]

Flag	Type	Default	Description
`--path`	path	`security.audit_log_path` or `<data_dir>/audit.jsonl`	Audit log file to verify

The audit log is enabled by default. The command reports the path it verified, the total entry count, and the result (ok or the index of the first broken link in the chain).

healthcheck

Lightweight HTTP health probe for container health checks.

bash

cerememory healthcheck [OPTIONS]

Flag	Type	Default	Description
`--port`	u16	`8420`	HTTP port to check

Returns exit code 0 when healthy and non-zero otherwise.

mcp

Start a stdio MCP proxy that forwards tool calls to an existing long-lived cerememory serve process. --server-url is required — cerememory mcp is a proxy only; there is no embedded-store MCP mode.

bash

cerememory serve --data-dir ~/.cerememory/data
cerememory mcp --server-url http://127.0.0.1:8420

Flag	Env Var	Required	Description
`--server-url`	—	Yes	URL of the shared `cerememory serve` process (e.g., `http://127.0.0.1:8420`)
`--server-api-key`	`CEREMEMORY_SERVER_API_KEY`	When upstream auth is enabled	Bearer token for the upstream Cerememory HTTP server
`--server-timeout-secs`	—	No	Optional per-request upstream timeout in seconds; omit to disable per-request timeout

The MCP server exposes these tools:

Tool	Description
`store`	Store a new memory record; accepts optional `meta_json`
`update`	Update an existing record's content, emotion, or `meta_json`
`batch_store`	Store multiple memories at once with inferred associations
`store_raw`	Store a verbatim raw journal entry; accepts optional `meta_json`
`batch_store_raw`	Store multiple raw journal entries; each entry may include `meta_json`
`recall`	Query memories, or list recent ones when `query` is omitted
`recall_raw`	Forensic query over the raw journal
`timeline`	Retrieve memories in time buckets
`associate`	Traverse the association graph from a record
`inspect`	Inspect a specific record
`forget`	Permanently delete records by UUID
`dream_tick`	Summarize raw journal into curated memory
`consolidate`	Trigger episodic-to-semantic consolidation
`stats`	View system statistics
`export`	Export curated memories and the raw journal to a CMA archive at an explicit output path

Next Steps

API Endpoints

HTTP REST endpoint reference

LLM Adapters

Configure Claude, GPT, and Gemini