AgentMemory Offline

Persistent, project-aware memory for local coding agents, derived from rohitg00/agentmemory.

This fork keeps memory on the machine and runs its memory services without outbound network access. It preserves the useful parts of AgentMemory—session capture, recall, summaries, semantic structure, MCP tools, hooks, and a local viewer—while disabling cloud model providers, telemetry, runtime downloads, and update checks.

What “offline” means

The runtime is designed so that memory content is never sent to a remote service:

• no cloud LLM provider is selected;
• no provider API key is required;
• no telemetry or update check is enabled;
• MCP points to the locally installed executable, never to npx;
• on macOS, the bundled engine is launched through sandbox-exec with non-loopback outbound traffic denied;
• local retrieval falls back to lexical/BM25 and the local graph.

Building or installing dependencies may still require access to npm and GitHub. That is outside the runtime guarantee. Linux and Windows do not currently get the macOS process-level network sandbox; use an OS firewall or container network policy there if you need an independently enforced boundary.

See docs/OFFLINE_SECURITY.md for the threat model, ports, limitations, and verification procedure.

Where memory is stored

The database and engine state live outside project repositories by default:

Platform	Default location
macOS	~/Library/Application Support/agentmemory
Linux	$XDG_DATA_HOME/agentmemory or ~/.local/share/agentmemory
Windows	%APPDATA%\agentmemory

Override the location with --data-dir <path> or AGENTMEMORY_DATA_DIR=<path>. Memory records carry project/session context, so multiple sessions for the same project can contribute to the same project memory without mixing their session history.

Architecture

Local agent
  ├─ lifecycle hooks ───────────────┐
  └─ MCP tools ────────────────┐    │
                               v    v
                     AgentMemory REST service :3111
                         ├─ local retrieval
                         ├─ local graph/index
                         ├─ session observations
                         └─ local viewer :3113
                                      │
                                      v
                              local iii engine

The default interfaces are local HTTP/MCP surfaces. Set AGENTMEMORY_SECRET to require bearer authentication even on localhost.

Build and run

Requirements: Node.js 20 or newer and the pinned iii engine version shown in src/version.ts.

npm install
npm run build
npm link

agentmemory --data-dir "$HOME/.local/share/agentmemory"

The application will not download the engine at runtime in offline mode. Install the pinned engine ahead of time while online, or place the compatible binary in the private AgentMemory bin directory.

For MCP-only clients:

{
  "mcpServers": {
    "agentmemory": {
      "command": "agentmemory",
      "args": ["mcp"],
      "env": {
        "AGENTMEMORY_URL": "http://127.0.0.1:3111"
      }
    }
  }
}

Host integration

The repository includes portable skills and lifecycle hooks. Installation must merge these declarations with the host's existing configuration; it must not replace unrelated hooks or skills. The MCP manifest calls the locally installed agentmemory executable.

Current limitations

• Runtime network enforcement is strongest on macOS.
• The iii engine may create an internal listener on port 49134. The macOS sandbox rejects non-loopback inbound traffic, but users on other systems must bind or firewall that port themselves.
• Optional vector embeddings are not part of the guaranteed offline profile. BM25 and graph retrieval remain available.
• Mesh/peer synchronization is outside the offline profile and must remain disabled.

Verification

npm test
npm run build
rg -n "OPENAI_API_KEY|ANTHROPIC_API_KEY|OPENROUTER_API_KEY" .env 2>/dev/null
lsof -nP -iTCP -sTCP:LISTEN | rg "3111|3112|3113|49134"

For a stronger test, deny all external traffic at the OS firewall, start the service, create a memory, stop it, start it again, and recall the same memory.

Provenance and license

This is an independent offline adaptation of AgentMemory. The original project and attribution are preserved in docs/UPSTREAM_README.md. Licensed under Apache-2.0; see LICENSE.