Features and Commands

Features and Commands

This page gives a practical map of what Recollectium can do across CLI, API, and MCP. For exhaustive command examples, see CLI Reference. For endpoint payloads, see API Reference. For MCP tool contracts, see MCP Server.

Memory operations

Feature	CLI	Main options	API	MCP	What it does
	Add memory	add	--space, --memory-space, --type, --content, --workspace-uid, --metadata, --source, --confidence, --sensitivity	POST /v1/memories	add_memory
	Search user memory	search-user	query, --memory-space, --type, --limit, --protected-minimum, --match-threshold, --include-archived	POST /v1/memories/search_user	search_user_memory
	Search workspace memory	search-workspace	query, --workspace-uid, --memory-space, --type, --limit, --protected-minimum, --match-threshold, --include-archived	POST /v1/memories/search_workspace	search_workspace_memory
	List memories	list	--space, --memory-space, --type, --status, --workspace-uid, --include-archived, --limit	GET /v1/memories	list_memories
	Get memory	get MEMORY_ID	MEMORY_ID, --memory-space	GET /v1/memories/{memory_id}	get_memory
	Update memory	update MEMORY_ID	--memory-space, --type, --content, --metadata, --source, --confidence, --sensitivity	PATCH /v1/memories/{memory_id}	update_memory
	Archive memory	archive MEMORY_ID	MEMORY_ID, --memory-space	POST /v1/memories/{memory_id}/archive	archive_memory

Workspace operations

Feature	CLI	Main options	API	MCP	What it does
	List workspaces	workspace list	--memory-space, --include-archived, --include-aliases	GET /v1/workspaces	list_workspaces
	Resolve workspace	workspace resolve UID	UID, --memory-space	GET /v1/workspaces/resolve?uid=...	resolve_workspace
	Rename workspace	workspace rename OLD_UID NEW_UID	OLD_UID, NEW_UID, --memory-space	POST /v1/workspaces/{uid}/rename	rename_workspace
	Add alias	workspace alias add	CANONICAL_UID, ALIAS_UID, --migrate-existing, --memory-space	POST /v1/workspaces/{uid}/aliases	add_workspace_alias
	List aliases	workspace alias list	--workspace UID, --memory-space	GET /v1/workspaces/{uid}/aliases	list_workspace_aliases
	Remove alias	workspace alias remove ALIAS_UID	ALIAS_UID, --memory-space	DELETE /v1/workspaces/aliases/{alias_uid}	remove_workspace_alias

Service and system operations

Feature	CLI	Options	What it does
	Initialize	init	none
Config inspect/edit	config	--path, --defaults, --validate, get, set, unset, init --force, doctor, edit, reset	Reads, validates, creates, edits, or resets configuration.
	Database status	db-status	--memory-space
	Seeded dev database	dev	true, false, reset, eval, optimize-threshold
Start service	service start api, service start mcp	service type: api or mcp	Starts a managed background service and writes discovery metadata.
Stop service	service stop	none	Stops the running managed service.
Service status	service status	none	Shows whether a managed service is running.
Service discovery	service discover	none	Prints adapter-friendly endpoint, version, capability, PID, and path metadata.
Restart service	service restart	--type api, --type mcp	Restarts the running or last-known service. Use --type if no service type can be inferred.
Foreground API	dev serve	--host, --port	Runs the API service in the foreground for debugging or development.
	MCP stdio	mcp-stdio	--config, --log-level
	Embedding status	embedding-status	--memory-space
	Embedding maintenance	embedding-maintenance	--memory-space
	Embedding jobs	embedding-jobs	--memory-space, --job-id, --state, --limit
	Force embedding refresh	embedding-refresh	--memory-space, --space, --workspace-uid, --include-archived
	Clear embedding job records	embedding-jobs-clear	--memory-space, --state, --yes
Shell completion	completion	SHELL, --source, --install, --yes	Prints or installs shell completion for bash, zsh, fish, or PowerShell.
Upgrade	upgrade	--check, --dry-run, --force, --install-method, --repo, --allow-main, --timeout	Checks and applies package upgrades through the detected install method, then runs embedding maintenance after successful updates.
Uninstall	uninstall	--purge, --yes-delete-all-recollectium-data, --dry-run	Preserves memories and config by default, removes the derived local model cache, and removes Recollectium-managed completion blocks. In human-readable mode, compact output is short and verbose output can show live progress. Source and unknown installs report a manual package-removal hint. With --purge, deletes Recollectium-owned local data after confirmation.

Global flags

These can be used before most commands:

Flag	What it does
	--config CONFIG_PATH
	--memory-space KEY
`--log-level debug	info
--json / --human-readable	Choose rendering. --json prints structured JSON and --human-readable prints terminal-friendly text.
--compact / --verbose	Choose response detail. --compact trims payloads and --verbose expands them.
--version	Prints the installed version.

Memory type buckets

User memory types:

• fact
• preference
• personal_fact
• social_context
• goal
• communication_style
• note

Workspace memory types:

• fact
• decision
• task_context
• configuration
• bug_finding
• note

Output contracts

CLI commands that return command data print human-readable summaries to stdout by default. When the target output stream is a TTY, human-readable output uses Rich-backed ANSI color for headings, field labels, errors, and hints. Non-TTY output stays plain text. Set cli_output to json in config, or pass --json, for scripts and adapters. Pass --human-readable to force terminal-friendly summaries for one invocation. Use --compact and --verbose to choose response detail without changing the rendering mode. --json and --human-readable are mutually exclusive and can appear before or after the command.

Protocol commands keep their machine contract regardless of cli_output: completion --source, completion candidate generation, dev serve, and mcp-stdio do not switch to human text.

Non-argparse command failures follow the same output format on stderr. In JSON mode they write a structured JSON object; in human-readable mode they write a readable message with status, detail, hint, and other fields. Validation and input errors usually exit 2. Runtime, service, database, migration, resource, not-found, and embedding errors usually exit 1.

The intentional exception is recollectium service discover: when no managed service is running, it exits 1, writes status: "not_running" output to stdout, and leaves stderr empty so adapters can read the discovery state. Use --json for adapter discovery calls if a user config may prefer human-readable output.