> ## Documentation Index
> Fetch the complete documentation index at: https://agent-memory.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot Agent Memory: Common Issues and Fixes

> Fix common Agent Memory issues: server not starting, agent not connecting, poor recall, high token usage, and more. Use agentmemory doctor for guided diagnostics.

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

```bash theme={null}
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:

```bash theme={null}
agentmemory doctor --all
```

To preview what would be fixed without changing anything:

```bash theme={null}
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

<AccordionGroup>
  <Accordion title="Server won't start">
    The most common cause is a stale process still holding port `3111`. Check what's bound:

    ```bash theme={null}
    # 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:

    ```bash theme={null}
    agentmemory stop --force
    ```

    If that doesn't clear it, kill the process by PID:

    ```bash theme={null}
    # macOS / Linux
    pkill -f agentmemory

    # Windows
    taskkill /F /PID <pid>
    ```

    Then start again:

    ```bash theme={null}
    agentmemory
    ```
  </Accordion>

  <Accordion title="Agent can't connect to Agent Memory">
    Your agent's MCP client needs to reach a running Agent Memory server before it can use any tools.

    <Steps>
      <Step title="Confirm Agent Memory is running">
        ```bash theme={null}
        agentmemory status
        ```

        If this returns an error or shows no active server, start it first: `agentmemory`
      </Step>

      <Step title="Re-run the connect command for your agent">
        ```bash theme={null}
        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.
      </Step>

      <Step title="Restart your agent">
        Most agents load MCP config at startup. Restart the agent after updating the config.
      </Step>
    </Steps>

    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.
  </Accordion>

  <Accordion title="Poor recall — agent doesn't seem to remember things">
    If your agent isn't recalling past context, work through these checks in order:

    **1. Enable context injection**

    By default, Agent Memory captures memories but doesn't inject them into conversation. To have past context appear automatically at session start:

    ```env theme={null}
    # ~/.agentmemory/.env
    AGENTMEMORY_INJECT_CONTEXT=true
    ```

    **2. Confirm the agent is using MCP tools**

    Run `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 recall**

    The 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):

    ```env theme={null}
    # ~/.agentmemory/.env
    CONSOLIDATION_ENABLED=true
    ```

    **4. Check the memory count**

    If 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.
  </Accordion>

  <Accordion title="Too many tokens being used">
    Agent Memory is designed to be token-efficient, but some configurations increase usage significantly:

    **Reduce the context injection budget**

    The default is 2000 tokens injected per session. Lower it:

    ```env theme={null}
    # ~/.agentmemory/.env
    TOKEN_BUDGET=800
    ```

    **Switch to core tools**

    Fewer tools means less token overhead for the agent to reason about:

    ```env theme={null}
    # ~/.agentmemory/.env
    AGENTMEMORY_TOOLS=core
    ```

    **Disable per-observation compression**

    `AGENTMEMORY_AUTO_COMPRESS=true` calls your LLM on every observation. Turn it off if you don't need LLM-compressed summaries:

    ```env theme={null}
    # ~/.agentmemory/.env
    AGENTMEMORY_AUTO_COMPRESS=false
    ```

    Synthetic compression (the default) handles indexing without LLM calls and works well for most use cases.
  </Accordion>

  <Accordion title="LLM API errors">
    If you see LLM errors in logs or poor memory quality, follow these steps:

    **1. Check your API key**

    Open `~/.agentmemory/.env` and confirm the key is present, uncommented, and correct. Keys must not have the `export` prefix.

    **2. Check which provider is active**

    ```bash theme={null}
    agentmemory status
    ```

    This shows the active LLM provider and model. If it shows `noop`, no key has been detected.

    **3. Test end-to-end**

    ```bash theme={null}
    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 order**

    Agent 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](/docs/guides/llm-providers) for details.
  </Accordion>

  <Accordion title="Can't find my project's memories">
    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 directory**

    Start 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**

    ```bash theme={null}
    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 viewer**

    Open `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.
  </Accordion>

  <Accordion title="Memory data is growing too large">
    Agent Memory is designed to grow over time, but if disk usage becomes a concern, you have a few options:

    **Delete old or irrelevant memories**

    Use 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:

    ```bash theme={null}
    curl -X DELETE http://localhost:3111/agentmemory/memories/mem_abc123 \
      -H "Authorization: Bearer your-secret"
    ```

    **Cap observations per session**

    Limit how many raw observations are stored per session before consolidation kicks in:

    ```env theme={null}
    # ~/.agentmemory/.env
    MAX_OBS_PER_SESSION=200
    ```

    The default is `500`. Observations beyond the cap trigger consolidation automatically.

    **Enable memory decay**

    When `CONSOLIDATION_ENABLED=true`, Agent Memory automatically evicts memories that haven't been accessed recently. The decay window defaults to 30 days:

    ```env theme={null}
    # ~/.agentmemory/.env
    CONSOLIDATION_DECAY_DAYS=14
    ```
  </Accordion>
</AccordionGroup>

## Verbose Logging

For deeper diagnostics, start Agent Memory with verbose output to see full stderr, MCP shim decisions, and provider detection:

```bash theme={null}
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:

```bash theme={null}
# Remove the Agent Memory installation but keep all stored memories
agentmemory remove --keep-data
```

To fully uninstall including all stored memory data:

```bash theme={null}
# 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`:

<Card title="GitHub Issues" icon="github" href="https://github.com/rohitg00/agentmemory/issues">
  Report a bug, ask a question, or search existing issues at github.com/rohitg00/agentmemory/issues
</Card>