> ## 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.

# Configure Agent Memory: Features, Ports, and Behavior

> Configure Agent Memory by editing ~/.agentmemory/.env. Enable consolidation, knowledge graphs, context injection, memory slots, and more.

All Agent Memory configuration lives in a single file: `~/.agentmemory/.env`. Running `agentmemory init` creates this file for you from the built-in template. Every setting is optional — Agent Memory runs out of the box with no configuration at all, using sensible defaults for every option.

## Quick Setup

<Steps>
  <Step title="Create the config file">
    ```bash theme={null}
    agentmemory init
    ```

    This copies the default `.env` template to `~/.agentmemory/.env`.
  </Step>

  <Step title="Open the file and uncomment the settings you want">
    ```bash theme={null}
    # macOS / Linux
    open ~/.agentmemory/.env
    # or edit directly
    nano ~/.agentmemory/.env
    ```

    On Windows, the file lives at `%USERPROFILE%\.agentmemory\.env`:

    ```powershell theme={null}
    notepad $HOME\.agentmemory\.env
    ```
  </Step>

  <Step title="Restart Agent Memory to apply changes">
    ```bash theme={null}
    agentmemory stop
    agentmemory
    ```
  </Step>
</Steps>

<Note>
  Restart Agent Memory after changing any `.env` setting. Environment variables set in your shell take precedence over values in the file.
</Note>

## Feature Flags

These flags are all `false` (or auto-detected) by default. Uncomment the ones you want in `~/.agentmemory/.env`.

| Variable                     | Default                  | Description                                                                                                                                                                                                                                |
| ---------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `AGENTMEMORY_AUTO_COMPRESS`  | `false`                  | Run LLM compression on every observation as it arrives. Produces richer summaries but increases API token usage proportionally with session activity.                                                                                      |
| `AGENTMEMORY_INJECT_CONTEXT` | `false`                  | Automatically inject recalled memories into agent prompts at session start. When enabled, the SessionStart hook writes up to `TOKEN_BUDGET` tokens of relevant project context into the first turn.                                        |
| `CONSOLIDATION_ENABLED`      | auto (on if LLM key set) | Run the 4-tier consolidation pipeline at session end. Moves memories from working → episodic → semantic → procedural. Automatically enabled when any LLM provider key is present; set `CONSOLIDATION_ENABLED=false` to explicitly opt out. |
| `GRAPH_EXTRACTION_ENABLED`   | `false`                  | Extract entities and relationships into a knowledge graph when memories are saved. Powers graph-traversal recall. Requires an LLM provider.                                                                                                |
| `AGENTMEMORY_SLOTS`          | `false`                  | Enable pinned, editable memory slots per project (persona, user\_preferences, tool\_guidelines, project\_context, pending\_items, and more). Agents can read and update slots via the `memory_slot_*` MCP tools.                           |
| `AGENTMEMORY_REFLECT`        | `false`                  | Automatically synthesize lessons from recent observations on the Stop hook. Requires `AGENTMEMORY_SLOTS=true`. Appends TODOs to `pending_items`, tracks patterns in `session_patterns`, and records touched files in `project_context`.    |
| `SNAPSHOT_ENABLED`           | `false`                  | Create periodic git-versioned snapshots of your memory state. Snapshots land in `~/.agentmemory/snapshots` by default (override with `SNAPSHOT_DIR`). Configure the interval with `SNAPSHOT_INTERVAL` (seconds; default `3600`).           |
| `CLAUDE_MEMORY_BRIDGE`       | `false`                  | Enable bi-directional sync between Agent Memory and your project's `CLAUDE.md` file. When on, set `CLAUDE_PROJECT_PATH=/path/to/your/project`. Controls how many lines are mirrored with `CLAUDE_MEMORY_LINE_BUDGET` (default `200`).      |

## Tool Visibility

The `AGENTMEMORY_TOOLS` variable controls how many MCP tools your agent sees:

```env theme={null}
# ~/.agentmemory/.env
AGENTMEMORY_TOOLS=all    # expose all 53 tools (default)
# AGENTMEMORY_TOOLS=core # expose only the 8 essential tools
```

| Value           | Tools exposed                                                                                                                                                                     | When to use                                                                  |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `all` (default) | 53 tools — full memory, team coordination, graph, governance, and multi-agent tools                                                                                               | Most setups                                                                  |
| `core`          | 8 essential tools — `memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, and `memory_reflect` | Agents with limited context windows, or when you want to minimize tool noise |

<Tip>
  Use `AGENTMEMORY_TOOLS=core` if your agent frequently hits context length limits. The 8 core tools cover the vast majority of memory operations.
</Tip>

## Ports

Agent Memory binds three public ports by default. You can override each one in `~/.agentmemory/.env`:

| Port   | Variable                  | Purpose                                             |
| ------ | ------------------------- | --------------------------------------------------- |
| `3111` | `III_REST_PORT`           | REST API, MCP HTTP transport, `/agentmemory/health` |
| `3112` | `III_STREAMS_PORT`        | Streams worker (used by the viewer)                 |
| `3113` | `AGENTMEMORY_VIEWER_PORT` | Real-time web viewer at `http://localhost:3113`     |

To move the REST API to a different port:

```env theme={null}
# ~/.agentmemory/.env
III_REST_PORT=4111
```

When you change `III_REST_PORT`, also update `AGENTMEMORY_URL` so the CLI and MCP shim know where to find the server:

```env theme={null}
III_REST_PORT=4111
AGENTMEMORY_URL=http://localhost:4111
```

## Multi-Instance: Running Multiple Projects Side-by-Side

If you work on multiple projects simultaneously, you can run separate Agent Memory instances — each with its own port set and data directory — using the `--instance` flag:

```bash theme={null}
# Instance 0 (default) — ports 3111, 3112, 3113
agentmemory

# Instance 1 — ports 3211, 3212, 3213
agentmemory --instance 1

# Instance 2 — ports 3311, 3312, 3313
agentmemory --instance 2
```

Each instance automatically shifts its entire port set by 100, so they never collide. Point each project's agent at its respective `AGENTMEMORY_URL`.

## Security

By default, the REST API is open on loopback (`127.0.0.1`) with no authentication. If you expose Agent Memory beyond localhost — for example, behind a reverse proxy or in a shared environment — set a bearer secret:

```env theme={null}
# ~/.agentmemory/.env
AGENTMEMORY_SECRET=your-secret-here
```

Once set, every API request must include:

```
Authorization: Bearer your-secret-here
```

The MCP shim and Agent Memory CLI read `AGENTMEMORY_SECRET` automatically. For Claude Code and other agents configured via the `mcpServers` block, pass it in the `env` section:

```json theme={null}
{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/mcp"],
      "env": {
        "AGENTMEMORY_URL": "http://localhost:3111",
        "AGENTMEMORY_SECRET": "your-secret-here"
      }
    }
  }
}
```

<Tip>
  Use `agentmemory status` at any time to see which feature flags are active, which LLM provider is in use, and the current port assignments.
</Tip>