Quickstart for agents

One page an AI coding agent can follow to set up SmartMemory for a project, run a smoke test and report back.

Agent: do not work from a summary of this page. Fetch tools that summarize (such as WebFetch in Claude Code) drop the exact commands, and setup then fails. If you can run shell commands, first download the full text with the command below, read all of it (do not cut it short with head or a byte limit), then follow that text from the top:

curl -fsSL https://smartmemory.ai/claude.md

This page is written for an AI agent (Claude Code, Cursor, Codex, Claude Desktop). A person can start it with one line:

Set up SmartMemory for this project: read https://smartmemory.ai/claude and do what it says

If you are an agent, read this first

This page is a set of steps for you to carry out now, not a document to summarize. Run the commands yourself, in order, until you reach the report at the end. Do not stop to describe the page or to ask the user which option they want.
Use the LOCAL branch. It is the default: free, no account, and memories stay on this machine. Use the HOSTED branch only when one of these is true:
1. the user asked for the hosted service, a SmartMemory account, or memory shared across machines or teammates
2. you cannot run shell commands (for example the Claude.ai chat or the Claude Desktop chat window)
3. Step 1 finds no Python 3.11, 3.12 or 3.13 on this machine
Do not switch to HOSTED because local setup downloads models or writes files outside the project. Both are expected and listed in Step 3. Mention them to the user in your progress notes and keep going, do not wait for an answer.
Two steps download a lot: installing the package (Step 2) and the first setup (Step 3). They take a few minutes on a fast connection and can take more than an hour on a slow one. Your tools may stop any command that runs longer than a few minutes, so this page starts both steps in the background with nohup, writes their output to a log file inside .venv, records the process number next to it, and gives you a short check command. Run the check again and again until it says the step is done. Run the start command and every check from the project folder, in the same order as on this page. A step that is still running is not a failure. Never kill it, and never start it a second time while it is still running.
The LOCAL branch has six steps: 1 check Python, 2 install, 3 setup, 4 register the MCP server, 5 add the memory instructions, 6 smoke test. You are done only when the search in Step 6 has returned the memory you added in Step 6. Never report a smoke test you did not run.
This page ends with the line END OF SMARTMEMORY SETUP INSTRUCTIONS. If the text you have does not reach that line, it was cut off: download it again and read the rest before you start.
When you finish, report back with the template in the last section.

LOCAL branch

Step 1. Check Python

SmartMemory needs Python 3.11, 3.12 or 3.13. Find one:

python3.13 --version
python3.12 --version
python3.11 --version
python3 --version

Use the first command that prints 3.11, 3.12 or 3.13, and write it where this page says python3. Prefer those three over a newer Python, because some dependencies publish ready-made wheels only for released versions they have tested. If none of them works, local setup is not possible on this machine yet: tell the user that it needs Python 3.12, and use the HOSTED branch unless they would rather install Python first.

Step 2. Install the package (in the background)

If the project already has a virtual environment (a .venv or venv folder with a bin/python inside) running Python 3.11 or newer, use it. If its folder is venv, write venv wherever this page says .venv. If the project has no virtual environment, create one in the project folder first:

python3 -m venv .venv

If you created .venv and the project has a .gitignore that does not list it, add a .venv/ line.

Start the install in the background (both lines, together). Its output goes to .venv/smartmemory-install.log, and its last line will be SMARTMEMORY-INSTALL-DONE or SMARTMEMORY-INSTALL-FAILED:

nohup sh -c '.venv/bin/python -m pip install --progress-bar off smartmemory && echo SMARTMEMORY-INSTALL-DONE || echo SMARTMEMORY-INSTALL-FAILED' > .venv/smartmemory-install.log 2>&1 &
echo $! > .venv/smartmemory-install.pid

Then check on it. This command waits up to 90 seconds and prints the newest lines of the log:

t=0
until grep -qE 'SMARTMEMORY-INSTALL-(DONE|FAILED)' .venv/smartmemory-install.log || [ "$t" -ge 90 ]
do
  sleep 5
  t=$((t + 5))
done
tail -n 3 .venv/smartmemory-install.log
kill -0 "$(cat .venv/smartmemory-install.pid)" 2>/dev/null && echo 'STILL INSTALLING: run this check again'

Read the output:

SMARTMEMORY-INSTALL-DONE: the install finished. Go on.
STILL INSTALLING: pip is still downloading (the log shows which package). Run the same check again, as many times as it takes. Do not start the install again.
SMARTMEMORY-INSTALL-FAILED: read the reason with tail -n 30 .venv/smartmemory-install.log. If it is a network error (a timeout, or a connection that was reset or refused), start the install again with the same nohup command, once. pip keeps the files it already downloaded. Any other error, or a second network failure, means stop and report FAILED at step 2 with those 30 lines.
Neither marker and no STILL INSTALLING: something outside pip stopped it. Start the install again with the same nohup command, then check again.

From here on, SM means the sm program inside that environment, .venv/bin/sm. Check it:

.venv/bin/sm --version

On Windows there is no nohup: run .venv\Scripts\python.exe -m pip install smartmemory directly with the longest timeout your tools allow, and use .venv\Scripts\sm.exe for SM.

Step 3. Run setup in local mode (in the background)

Setup needs no account and no API key. An LLM key (for example GROQ_API_KEY or OPENAI_API_KEY) is optional and only improves entity extraction. The first run downloads about 300 MB of models, so it also starts in the background (both lines, together) and logs to .venv/smartmemory-setup.log:

nohup sh -c '.venv/bin/sm setup --mode local --yes && echo SMARTMEMORY-SETUP-DONE || echo SMARTMEMORY-SETUP-FAILED' > .venv/smartmemory-setup.log 2>&1 &
echo $! > .venv/smartmemory-setup.pid

Check on it the same way:

t=0
until grep -qE 'SMARTMEMORY-SETUP-(DONE|FAILED)' .venv/smartmemory-setup.log || [ "$t" -ge 90 ]
do
  sleep 5
  t=$((t + 5))
done
tail -n 5 .venv/smartmemory-setup.log
kill -0 "$(cat .venv/smartmemory-setup.pid)" 2>/dev/null && echo 'STILL SETTING UP: run this check again'

SMARTMEMORY-SETUP-DONE: go on to Step 4.
STILL SETTING UP: it is downloading models or starting the background service. Run the same check again. Do not start setup again.
SMARTMEMORY-SETUP-FAILED: read tail -n 30 .venv/smartmemory-setup.log. If it says "SmartMemory daemon did not start or become ready", that a port "is used by another program", or that some checks failed, the background service is usually still loading its models. Do NOT run setup again and do NOT run sm restart, because both start the loading over. Instead run this check, up to 5 times, until it prints SmartMemory daemon: ok:

t=0
until .venv/bin/sm status 2>&1 | grep -q 'SmartMemory daemon: ok' || [ "$t" -ge 90 ]
do
  sleep 10
  t=$((t + 10))
done
.venv/bin/sm status

If it is still not ok after that, run .venv/bin/sm doctor and include its output in your report. Any other setup failure: stop and report FAILED at step 3 with the last 30 lines of the log.

What setup changes outside the project, so you can tell the user:

memories are stored in ~/.smartmemory and settings in ~/.config/smartmemory/config.toml
it installs SmartMemory hooks and skills for Claude Code in ~/.claude (automatic recall and capture in every project)
on macOS it adds a login item (launchd) that keeps a small local background service running
sm uninstall removes the hooks, skills, login item and settings

Step 4. Register the MCP server for this project only

Use PROJECT scope, so the server is recorded in this project and not in the user's global configuration. The command must be an absolute path.

Claude Code (run from the project folder):

claude mcp add --scope project smartmemory -e SMARTMEMORY_MCP_MODE=local -- "$PWD/.venv/bin/smartmemory-mcp"
claude mcp get smartmemory

claude mcp get should show Scope: Project config and the path you gave. A status of "Pending approval" is expected: the user approves the server the next time Claude Code starts in this project, and the tools load in that new session, not in this one.

If the claude command is not available, create .mcp.json in the project folder with this content, using the real absolute path:

{
  "mcpServers": {
    "smartmemory": {
      "type": "stdio",
      "command": "/absolute/path/to/project/.venv/bin/smartmemory-mcp",
      "args": [],
      "env": { "SMARTMEMORY_MCP_MODE": "local" }
    }
  }
}

Cursor: create .cursor/mcp.json in the project folder with the same mcpServers block (Cursor reads project MCP servers from that file).

Claude Desktop has no project scope. Its file is ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows. Ask the user before you edit it, add the same smartmemory entry under mcpServers, and tell them to restart Claude Desktop.

.mcp.json holds an absolute path that only works on this machine. Tell the user before they commit it.

Step 5. Add the memory instructions to the project

Append this block to CLAUDE.md in the project root (Claude Code). For Cursor, Codex and other agents append it to AGENTS.md. Create the file if it does not exist. Do not add the block twice.

## Memory (SmartMemory)

This project has long-term memory through the `smartmemory` MCP server.

- At the start of a task, and before answering a question about earlier decisions or conventions, call `memory_search` with a short plain-language query.
- To read one result in full, call `memory_get` with its item id.
- After a decision, a fix whose cause was not obvious, or a convention the user states, call `memory_ingest` with one or two plain sentences that say what was decided and why.

Never store secrets, keys, passwords or personal data.

Step 6. Smoke test

Add one true memory and recall it. Run the lines exactly as written, from the project folder: the shell fills in the folder name and today's date, so do not edit, shorten or retype them.

.venv/bin/sm add "SmartMemory was set up for the $(basename "$PWD") project on $(date +%Y-%m-%d) by an AI agent following smartmemory.ai/claude"
.venv/bin/sm search "when was SmartMemory set up for this project"

The search output must contain the sentence you added. If sm add reports a timeout, run the search before you add again, because the add usually completed. If the search does not return it, run .venv/bin/sm status and .venv/bin/sm doctor and include both outputs in your report.

HOSTED branch

Use this branch only in the three cases listed at the top of this page: the user asked for the managed service (memory shared across machines and teammates), you cannot run shell commands, or this machine has no Python 3.11 to 3.13. It ends with ONE step only the user can do: approve the sign-in in a browser.

Claude Code:

claude mcp add --scope project --transport http smartmemory https://mcp.smartmemory.ai/mcp

Cursor: add this to .cursor/mcp.json in the project folder.

{
  "mcpServers": {
    "smartmemory": { "url": "https://mcp.smartmemory.ai/mcp" }
  }
}

Claude.ai or Claude Desktop: tell the user to add a custom connector with the URL https://mcp.smartmemory.ai/mcp in the connector settings.

Then tell the user: "Restart your agent in this project. The first SmartMemory tool call opens a browser tab. Sign in or create a free account there and approve the connection." That click is the only human step. Add the Step 5 memory instructions to the project as well.

Facts for the user:

The Free plan has 10,000 memories, 200 queries a day, 1 indexed code repository and 1 seat. Current figures: https://www.smartmemory.ai/pricing
The hosted MCP server exposes 25 tools and signs in with OAuth. Details: https://docs.smartmemory.ai/smartmemory/guides/hosted-mcp/
REST API base URL: https://api.smartmemory.ai. Authenticate with X-API-Key: YOUR_API_KEY (an API key from the SmartMemory web app) or Authorization: Bearer YOUR_SESSION_TOKEN. Most routes also need X-Workspace-Id. Header reference: https://docs.smartmemory.ai/smartmemory/guides/authentication-and-tenancy/
OpenAPI schema: https://api.smartmemory.ai/openapi.json
When SmartMemory is the wrong tool: https://docs.smartmemory.ai/smartmemory/getting-started/when-not-to-use/

Report back to the user

End with a short report in exactly this shape. Copy the lines as plain text inside a code block, keep each label exactly as written (no bold, no bullets, no renamed labels), and fill in the parts in angle brackets. People and tools read these lines. You may add notes below the block.

SmartMemory setup: DONE (local) | DONE (hosted, waiting for your sign-in) | FAILED at step N
Installed: smartmemory <version from sm --version> in <environment path>
MCP: registered for this project in <file>. Restart your agent here and approve "smartmemory" to load the tools.
Instructions: added to <CLAUDE.md or AGENTS.md>
Smoke test: <PASS, with the recalled line> | <FAIL, with the error>
Changed outside this project: <list from Step 3, or "nothing" for hosted>
Next: <what the user should do, if anything>

END OF SMARTMEMORY SETUP INSTRUCTIONS

Quickstart for agents

On this page