@ledgermem/cli

The official command-line interface for LedgerMem — a verifiable, append-only memory layer for AI agents.

ledgermem lets you create, search, and manage memories from your terminal, plus drop a turnkey MCP config snippet into Claude Desktop or Cursor.

Install

npm install -g @ledgermem/cli

Or run without installing:

npx @ledgermem/cli --help

Quickstart

ledgermem login                       # save API key + workspace to ~/.ledgermem/config.json
ledgermem add "Acme prefers blue branding"
ledgermem search "what brand color does Acme use?"
ledgermem doctor                      # verify auth + API reachability

Commands

Authentication

Command	Description
ledgermem login	Prompt for API key, workspace ID, and (optionally) API URL; persist to ~/.ledgermem/config.json.
ledgermem logout	Remove saved credentials.
ledgermem whoami	Print the active workspace + API URL.

login flags: --api-key, --workspace-id, --api-url (skip the prompt).

Memory operations

Command	Description
ledgermem add "<content>" [-m key=value ...]	Add a memory with optional metadata.
ledgermem search "<query>" [--limit 5]	Semantic search.
ledgermem get <id>	Fetch a single memory.
ledgermem rm <id> [--yes]	Delete a memory.
ledgermem list [--limit 20] [--cursor <c>]	Paginate the workspace.

Workspaces

Command	Description
ledgermem workspace list	List workspaces from local config.
ledgermem workspace switch <id>	Switch the active workspace.

Other

Command	Description
ledgermem mcp [--client claude|cursor]	Print an MCP server config snippet.
ledgermem doctor	Check auth + GET /healthz.

Global flags

• --json — emit machine-readable JSON instead of pretty output. Honoured by every command.
• --version / -v
• --help / -h

Exit codes

Code	Meaning
0	Success
1	Runtime error (auth missing, API failure, not found, ...)
2	Invalid arguments / unknown command

Environment variables

Variable	Purpose	Default
LEDGERMEM_API_KEY	Overrides the saved API key.	—
LEDGERMEM_WORKSPACE_ID	Overrides the active workspace.	—
LEDGERMEM_API_URL	Overrides the API base URL.	https://api.proofly.dev

Environment variables take precedence over ~/.ledgermem/config.json.

Examples

# add a tagged memory
ledgermem add "Customer asked about SOC 2 timeline" -m customer=acme -m channel=email

# JSON output for piping into jq
ledgermem search "soc 2" --limit 3 --json | jq '.results[].id'

# delete without prompting (CI-safe)
ledgermem rm mem_01HX... --yes

# generate Claude Desktop MCP config
ledgermem mcp --client claude > claude_desktop_config.json

Development

npm install
npm run dev -- --help    # run from source via tsx
npm run build            # compile to dist/
npm test                 # vitest

License

MIT