Help

Troubleshooting

Start with oort doctor. It checks your setup and prints a fix for each problem it finds.

1
Run the checks.
Terminal
```
$ oort doctor
```
It looks at your keys (only whether they are set, never their values), the Claude Code hooks, each connected agent, the memory store, and whether the Oort Pro relay answers.
Run the fix it prints for each failure.
Run oort doctor again until every check passes.

Common fixes

oort: command not found

Terminal

$ node --version
$ npm i -g oortmem

Oort needs Node.js 22.15 or newer. Then open a new terminal.

My agent does not list oort

Quit the agent fully and start it again. If it is still missing, connect it again. This is safe to repeat: it says "already connected" when nothing needs to change.

Terminal

$ oort connect cursor

Agent	Where to look
Claude Code, Gemini CLI	`/mcp`
Codex	`codex mcp list`
Cursor	Settings, then MCP
VS Code	MCP: List Servers

oort connect refuses to edit a file

Exit code 2 means Oort will not touch that file. Either the file is not valid JSON, or it already has an oort entry that you wrote yourself. Fix the JSON, or rename your entry, then connect again. Oort keeps the original file next to it, ending in .oort-backup, and the state before its last change in .oort-prev.

"lexical-only recall"

Oort has no keys, so it matches on words only and cannot save new memories. See which key is missing:

Terminal

$ oort keys list

Then sign in with oort login (Oort Pro) or set your own keys, and restart your agents.

Claude Code started billing the API

ANTHROPIC_API_KEY is set in your shell. Remove it from your shell profile and store the key with oort keys set anthropic instead.

The wrong project's memories show up

The server uses the folder its agent starts it in. Pin a folder with --project /path/to/repo in the agent's args. If your repository names a project in oort.config.json, trust it once:

Terminal

$ oort project link

Setup fails in CI or a script

Without a terminal, setup asks nothing. Pass every answer as a flag:

Terminal

$ oort setup --yes --agents claude-code --keys byo --import skip

I need the full error

Add --debug to any command to print the stack trace.

Start over

Terminal

$ oort uninstall claude-code
$ oort disconnect cursor codex
$ oort keys rm voyage
# deletes every memory
$ rm -r ~/.oort

Still stuck? Open an issue on GitHub.