Configure Agent Memory: Features, Ports, and Behavior

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

Create the config file

agentmemory init

This copies the default .env template to ~/.agentmemory/.env.

Open the file and uncomment the settings you want

# macOS / Linux
open ~/.agentmemory/.env
# or edit directly
nano ~/.agentmemory/.env

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

notepad $HOME\.agentmemory\.env

Restart Agent Memory to apply changes

agentmemory stop
agentmemory

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

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:

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

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

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:

# ~/.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:

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:

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

# ~/.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:

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

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

​Quick Setup

​Feature Flags

​Tool Visibility

​Ports

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

​Security

Quick Setup

Feature Flags

Tool Visibility

Ports

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

Security