Skip to main content
Agent Memory includes a built-in diagnostic tool that checks your installation, config, and running processes — and can apply fixes automatically. Most issues can be resolved without manual investigation.

​
Start with Doctor

agentmemory doctor
Doctor walks through a checklist of known issues and prompts you for each one:
  • F — apply the fix automatically
  • S — skip this check
  • ? — show more information about the issue
  • Q — quit
To apply all detected fixes without prompting: 
agentmemory doctor --all
To preview what would be fixed without changing anything: 
agentmemory doctor --dry-run
Run agentmemory doctor first whenever something isn’t working. It catches the most common issues — misconfigured MCP wiring, stale port bindings, missing env variables, and agent hook mismatches.

​
Common Issues

The most common cause is a stale process still holding port 3111. Check what’s bound:
# macOS / Linux
lsof -i :3111
lsof -i :3111,3112,3113

# Windows
netstat -ano | findstr ":3111"
Stop Agent Memory cleanly — including any orphaned processes from a previous crashed run:
agentmemory stop --force
If that doesn’t clear it, kill the process by PID:
# macOS / Linux
pkill -f agentmemory

# Windows
taskkill /F /PID <pid>
Then start again:
agentmemory
Your agent’s MCP client needs to reach a running Agent Memory server before it can use any tools.
1

Confirm Agent Memory is running

agentmemory status
If this returns an error or shows no active server, start it first: agentmemory
2

Re-run the connect command for your agent

agentmemory connect claude-code
# or: agentmemory connect cursor
# or: agentmemory connect codex
# etc.
This refreshes the MCP server block in your agent’s config file with current paths and settings.
3

Restart your agent

Most agents load MCP config at startup. Restart the agent after updating the config.
If the agent is in a sandboxed environment (Flatpak, Snap, or a restricted container) that can’t reach localhost, add AGENTMEMORY_FORCE_PROXY=1 to the MCP server env block and set AGENTMEMORY_URL to a network address the sandbox can reach.
If your agent isn’t recalling past context, work through these checks in order:1. Enable context injectionBy default, Agent Memory captures memories but doesn’t inject them into conversation. To have past context appear automatically at session start:
# ~/.agentmemory/.env
AGENTMEMORY_INJECT_CONTEXT=true
2. Confirm the agent is using MCP toolsRun agentmemory status and look at the tool call counts. Zero calls means the hooks aren’t wired or the agent isn’t using the tools. Re-run agentmemory connect <agent> and check the agent’s plugin/MCP configuration.3. Enable consolidation for better long-term recallThe 4-tier consolidation pipeline significantly improves recall quality over time. Make sure it’s enabled (it auto-enables when any LLM key is set, but you can force it):
# ~/.agentmemory/.env
CONSOLIDATION_ENABLED=true
4. Check the memory countIf the server was recently reset or this is a fresh install, there may simply not be enough memories yet. Run agentmemory demo to seed sample sessions and verify recall is working at all.
Agent Memory is designed to be token-efficient, but some configurations increase usage significantly:Reduce the context injection budgetThe default is 2000 tokens injected per session. Lower it:
# ~/.agentmemory/.env
TOKEN_BUDGET=800
Switch to core toolsFewer tools means less token overhead for the agent to reason about:
# ~/.agentmemory/.env
AGENTMEMORY_TOOLS=core
Disable per-observation compressionAGENTMEMORY_AUTO_COMPRESS=true calls your LLM on every observation. Turn it off if you don’t need LLM-compressed summaries:
# ~/.agentmemory/.env
AGENTMEMORY_AUTO_COMPRESS=false
Synthetic compression (the default) handles indexing without LLM calls and works well for most use cases.
If you see LLM errors in logs or poor memory quality, follow these steps:1. Check your API keyOpen ~/.agentmemory/.env and confirm the key is present, uncommented, and correct. Keys must not have the export prefix.2. Check which provider is active
agentmemory status
This shows the active LLM provider and model. If it shows noop, no key has been detected.3. Test end-to-end
agentmemory demo
The demo seeds test sessions and runs searches. If this fails, the LLM call path is broken — check the key and provider config.4. Check provider detection orderAgent Memory checks keys in this order: OPENAI_API_KEY → MINIMAX_API_KEY → ANTHROPIC_API_KEY → GEMINI_API_KEY → OPENROUTER_API_KEY. If you set multiple keys, the first one in that order wins. See the LLM Providers guide for details.
Agent Memory scopes memories by project directory. If you start your agent from a different working directory than you used previously, memories from the earlier sessions won’t appear in searches.1. Make sure you’re running from the same directoryStart your agent from the root of the project you want to recall memories for. Agent Memory records the working directory with each session.2. Browse sessions to find the right project
agentmemory status
This lists recent sessions with their project paths. You can also use the memory_sessions MCP tool from inside your agent to browse sessions and confirm which project path they’re scoped to.3. Check the real-time viewerOpen http://localhost:3113 and browse the Sessions tab. You can see all sessions, their project paths, observation counts, and timestamps — useful for confirming where your memories actually live.
Agent Memory is designed to grow over time, but if disk usage becomes a concern, you have a few options:Delete old or irrelevant memoriesUse the memory_governance_delete MCP tool from inside your agent to remove specific memories with a full audit trail. You can also call the REST API:
curl -X DELETE http://localhost:3111/agentmemory/memories/mem_abc123 \
  -H "Authorization: Bearer your-secret"
Cap observations per sessionLimit how many raw observations are stored per session before consolidation kicks in:
# ~/.agentmemory/.env
MAX_OBS_PER_SESSION=200
The default is 500. Observations beyond the cap trigger consolidation automatically.Enable memory decayWhen CONSOLIDATION_ENABLED=true, Agent Memory automatically evicts memories that haven’t been accessed recently. The decay window defaults to 30 days:
# ~/.agentmemory/.env
CONSOLIDATION_DECAY_DAYS=14

​
Verbose Logging

For deeper diagnostics, start Agent Memory with verbose output to see full stderr, MCP shim decisions, and provider detection: 
agentmemory --verbose
Verbose mode shows which LLM provider was detected, which ports bound successfully, and any errors from hook scripts or API calls. It’s the fastest way to diagnose startup failures and provider configuration issues.

​
Reset Everything

If you want a clean slate without losing your memory data: 
# Remove the Agent Memory installation but keep all stored memories
agentmemory remove --keep-data
To fully uninstall including all stored memory data: 
# Remove everything — installation AND all memories (irreversible)
agentmemory remove
After either command, reinstall with npm install -g @agentmemory/agentmemory and run agentmemory init to restore the config template.

​
Getting Help

If you’re still stuck after running agentmemory doctor and checking the sections above, open an issue on GitHub with the output of agentmemory status and agentmemory doctor --dry-run:

GitHub Issues

Report a bug, ask a question, or search existing issues at github.com/rohitg00/agentmemory/issues