Agent setup

For humans: one prompt

Paste this into Claude Code, Cursor, or any agent that can run commands and fetch a URL.

Set up memloom on this machine. Fetch https://docs.memloom.dev/guides/agent-setup
and follow it exactly. Ask me before anything that spends money or captures a
project. I will give you the API key when you ask.

If your agent supports skills:

npx skills add memloom/memloom

That adds memloom-setup, this runbook condensed, and memloom-use, how to use memloom well day to day.

For agents: ground rules

Everything below is yours to do autonomously, except two things.

The API key. Ask for OPENROUTER_API_KEY when the step comes. If the human declines, continue offline and say that recall quality is degraded until a key is set. Never print the key into logs, chat, or command output.Consent for capture and paid imports. Never run memloom connect claude-code or a non-dry-run import without the human naming the scope.

Report each step briefly. If one fails, check Troubleshooting before improvising.

Steps

Check Node

node --version

Expect v20 or later. If older, stop and ask the human to upgrade. npm silently skips the install otherwise.

Install and initialize

npm install -g memloom
memloom init

Creates ~/.memloom and starts the daemon. Expect the config path and http://127.0.0.1:4319.

Ask for the API key

Add it to ~/.memloom/config.env, then restart:

OPENROUTER_API_KEY=sk-or-...

memloom stop && memloom init

If anything was saved before the key was set, the daemon refuses to start, because offline and cloud vectors live in different spaces. Run memloom stop, memloom reembed, memloom init.

claude mcp add memloom -- npx -y @memloom/mcp

For other clients see the client pages. The shape is always the same: run npx -y @memloom/mcp as a stdio server.

Connect Claude Code

Ask which projects may be captured, then:

memloom connect claude-code --project <name>

Repeat per project, or --all only with explicit approval. Installs two hooks: session-end capture and prompt-time recall. Both merge with existing hooks, and a backup is written first.

Import what exists

memloom import agent-memory --dry-run   # free
memloom import sessions --dry-run       # spends model calls

Show the human each result and get approval before running without --dry-run.

Verify

memloom save "memloom setup verified on this machine"
memloom recall "setup verified"
memloom status

Expect the saved memory as the top hit, the same hit from the MCP client’s recall_memory, and a status showing the daemon running with the chosen capture scope.

Troubleshooting

Symptom	Cause and fix
`command not found` after install	Node older than 20, so npm skipped the package. Upgrade and reinstall
Daemon not reachable	Run `memloom init`. Every CLI command auto-starts it except the hooks
503 “store is locked”	A Postgres client holds the single-connection lock. Close it
Refuses to start on an embedding mismatch	`memloom stop`, `memloom reembed`, `memloom init`
Port 4319 in use	Another daemon is already running. That is fine, every client shares it
Postgres wire says OFF	Port 54329 will not bind. Set `MEMLOOM_PG_PORT` below 49152 and restart. The API and viewer work either way
`import sessions` refuses	Distillation needs a model, so set `OPENROUTER_API_KEY`

Getting Started

Concepts

Guides

For humans: one prompt

For agents: ground rules

Steps

Troubleshooting

​For humans: one prompt

​For agents: ground rules

​Steps

​Troubleshooting

For humans: one prompt

For agents: ground rules

Steps

Troubleshooting