CLI reference

Derived from sodamem_cli/main.py and sodamem_cli/targets.py.

sodamem <command> [options]

command	what it does
clients	list the coding tools install supports
install	write a client's MCP (and hook) configuration
daemon	the single store-owning service
hook	called by a coding tool's hooks; reads its event on stdin

Service flags

Accepted by install, daemon and hook:

flag	default
--api-url	$SODAMEM_API_URL, else http://127.0.0.1:8000
--api-key	$SODAMEM_API_KEY

clients

sodamem clients

Prints every install target with its config path and whether it also gets hooks.

target	scope	config file
claude-code	project	.mcp.json (+ .claude/settings.json hooks)
claude-desktop	user	Library/Application Support/Claude/claude_desktop_config.json (macOS)
cursor	user	.cursor/mcp.json (+ ~/.cursor/hooks.json)
cursor-project	project	.cursor/mcp.json
vscode	project	.vscode/mcp.json
windsurf	user	.codeium/windsurf/mcp_config.json
zed	user	.config/zed/settings.json
codex	user	.codex/config.toml (+ ~/.codex/hooks.json)
codex-project	project	.codex/config.toml — Codex loads project config only for trusted projects
copilot-cli	user	.copilot/mcp-config.json (+ ~/.copilot/hooks/sodamem.json)
opencode	user	.config/opencode/opencode.json

Config keys differ on purpose

VS Code reads servers, Codex reads mcp_servers, Zed reads context_servers and nests the command. Using the wrong key means the client ignores the file with no error at all, which is why install exists.

install

sodamem install claude-code
sodamem install cursor vscode zed          # several at once
sodamem install claude-code --dry-run      # print what would change

flag	meaning
clients	one or more target names (positional, at least one)
--user-id	memory owner (default: your OS username)
--project-id	repo scope (default: derived from the git root)
--no-project	do not scope this client to a project
--local-store PATH	have this client open the stores itself instead of using the service
--no-hooks	MCP tools only — skip automatic recall/retain
--dry-run	print what would be written, write nothing
--root PATH	repo root for project-scoped configs (default: the git root above the cwd)

Existing configuration is merged, not replaced: other MCP servers, other settings and hand-written TOML comments survive. The first write of any file leaves a .sodamem-backup beside it.

--local-store with more than one client

Per-user stores are SQLite without WAL — exactly one process may open them. A second client pointed at the same local store refuses to start rather than corrupting the first one's data. Use the service instead.

daemon

sodamem daemon ensure     # start one if none is answering (idempotent)
sodamem daemon status     # what is actually answering
sodamem daemon stop       # stop the one this machine started

flag	applies to	default
--data-root	ensure	~/.sodamem/data

ensure reports missing extraction credentials up front rather than accepting every write and failing the job afterwards — recall works without them, retain does not.

hook

sodamem hook recall --client claude-code
sodamem hook retain --client copilot-cli

You do not normally run this yourself; install wires it into the client's hook configuration. It reads the client's event on stdin.

argument	values
action	recall | retain
--client	claude-code, copilot-cli, cursor, codex, generic
--user-id, --project-id	override the scope

Clients disagree about payload shape, and the differences are real: Copilot CLI uses camelCase keys and injects additionalContext; Cursor's sessionStart carries no cwd and no prompt, and cannot retain. hook normalizes them.

Next

• Coding assistants — which client gets what
• MCP tools