🧠 AgentMemory Server — Centralized AI Memory Hub in Docker

Official repository for deploying a centralized agentmemory Hub (v0.9.29 + Rust iii engine v0.11.2) using Docker Compose.

It enables a shared, persistent 24/7 memory hub for AI coding agents (such as Antigravity agy, Cursor, Claude Code, etc.) across multiple client machines connected via VPN (e.g. Tailscale) or local area networks, optionally accelerated by a central Ollama server.

---

🛠️ Prerequisites

• A Linux host with Docker Engine and Docker Compose installed (e.g. Ubuntu Server, Debian, or any homelab server OS).
• A running Ollama instance (local or remote).
• Network connectivity (VPN, local subnet, or Tailscale) between your client machines and the host server.

---

🏗️ Solution Architecture

The stack consists of 2 containerized services sharing the same internal network stack (network_mode: "service:agentmemory"):

1. agentmemory-server: Main Node.js daemon + Rust iii-engine (ports 3111 for REST API and 3112 for WebSockets).
2. agentmemory-nginx-viewer: An Nginx server (nginx:alpine) acting as a reverse proxy on port 3114 to expose the web visualization UI and WebSocket live streams securely.

                  ┌────────────────────────────────────────────────────────┐
                  │                 Central Memory Server                  │
                  │                                                        │
                  │   ┌────────────────────────────────────────────────┐   │
 Client Linux     │   │           Docker Stack (agentmemory)           │   │
(Antigravity) ───┼──>│  - REST API (Port 3111)                         │   │
   [VPN / LAN]    │   │  - Stream WS (Port 3112)                       │   │
                  │   │  - Web Viewer Nginx (Port 3114)                │   │
 Client macOS ────┼──>│  - Database: SQLite (./data/state_store.db)    │   │
(Antigravity)     │   └───────────────────────┬────────────────────────┘   │
                  │                           │                            │
                  │                           ▼                            │
                  │                     Ollama Server                      │
                  │              http://<ollama-server-ip>:11434           │
                  └────────────────────────────────────────────────────────┘

---

📄 Configuration Files

1. docker-compose.yml

services:
  agentmemory:
    build: .
    container_name: agentmemory-server
    restart: always
    command: sh -c "node /usr/local/lib/node_modules/@agentmemory/agentmemory/dist/index.mjs & /root/.agentmemory/bin/iii --config /home/node/app/iii-config.yaml"
    environment:
      - OPENAI_API_KEY=ollama
      - OPENAI_BASE_URL=http://<ollama-server-ip>:11434/v1
      - OPENAI_MODEL=qwen2.5-coder:7b
      - AGENTMEMORY_AUTO_COMPRESS=true
      - GRAPH_EXTRACTION_ENABLED=true
      - CONSOLIDATION_ENABLED=true
      - AGENTMEMORY_INJECT_CONTEXT=true
      - AGENTMEMORY_URL=http://<server-ip>:3111
      - NODE_OPTIONS=--max-old-space-size=1024
    volumes:
      - ./data:/home/node/data
      - ./agentmemory_cache:/root/.agentmemory
      - ./iii-config.yaml:/home/node/app/iii-config.yaml
    ports:
      - "3111:3111"
      - "3112:3112"
      - "3114:3114"

  nginx-viewer:
    image: nginx:alpine
    container_name: agentmemory-nginx-viewer
    restart: always
    network_mode: "service:agentmemory"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      - agentmemory

(Note: Adjust ./data and ./agentmemory_cache paths to valid directories on your host server).

(Note: NODE_OPTIONS=--max-old-space-size=1024 caps the V8 heap at 1GB. Without it, /agentmemory/health may report memory_heap_tight_9x% warnings shortly after startup — this reflects V8's default small initial heap growing on demand, not an actual memory shortage (the container itself has no Docker memory limit by default). Tune the value up if your workload is heavier.)

2. Dockerfile

FROM node:20-slim
RUN apt-get update && apt-get install -y curl tar ca-certificates procps && rm -rf /var/lib/apt/lists/*
RUN npm install -g @agentmemory/agentmemory@0.9.29
RUN mkdir -p /root/.agentmemory/bin && curl -fsSL "https://github.com/iii-hq/iii/releases/download/iii/v0.11.2/iii-x86_64-unknown-linux-gnu.tar.gz" | tar -xz -C /root/.agentmemory/bin && chmod +x /root/.agentmemory/bin/iii
WORKDIR /home/node
ENV HOME=/home/node
EXPOSE 3111 3112 3113
CMD ["/root/.agentmemory/bin/iii", "--config", "/home/node/app/iii-config.yaml"]

3. iii-config.yaml

workers:
  - name: iii-http
    config:
      port: 3111
      host: 0.0.0.0
      default_timeout: 180000
      cors:
        allowed_origins: ["http://localhost:3111", "http://localhost:3113", "http://127.0.0.1:3111", "http://127.0.0.1:3113", "http://<server-ip>:3111", "http://<server-ip>:3113", "http://<server-ip>:3114"]
        allowed_methods: [GET, POST, PUT, DELETE, OPTIONS]
  - name: iii-state
    config:
      adapter:
        name: kv
        config:
          store_method: file_based
          file_path: /home/node/data/state_store.db
  - name: iii-queue
    config:
      adapter:
        name: builtin
  - name: iii-pubsub
    config:
      adapter:
        name: local
  - name: iii-cron
    config:
      adapter:
        name: kv
  - name: iii-stream
    config:
      port: 3112
      host: 0.0.0.0
      adapter:
        name: kv
        config:
          store_method: file_based
          file_path: /home/node/data/stream_store
  - name: iii-observability
    config:
      enabled: true
      service_name: agentmemory
      exporter: memory
      sampling_ratio: 0.1
      metrics_enabled: true
      logs_enabled: true
      logs_console_output: false

4. nginx.conf

server {
    listen 3114;
    server_name <server-ip> localhost;

    location = / {
        return 302 /viewer?wsPort=3114;
    }

    location = /viewer {
        if ($arg_wsPort = "") {
            return 302 /viewer?wsPort=3114;
        }
        proxy_pass http://127.0.0.1:3113;
        proxy_set_header Host localhost:3113;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    location /stream/ {
        proxy_pass http://127.0.0.1:3112/;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
    }

    location / {
        proxy_pass http://127.0.0.1:3113;
        proxy_set_header Host localhost:3113;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

---

🚀 Deployment Guide (Step-by-Step)

1. Create the stack folder on your host server:

   mkdir -p /opt/agentmemory-server
   cd /opt/agentmemory-server

2. Save the configuration files (docker-compose.yml, Dockerfile, iii-config.yaml, nginx.conf) in that folder. (Make sure to replace <server-ip> and <ollama-server-ip> with your actual network settings).

3. Deploy with Docker Compose:

   docker compose build --no-cache
   docker compose up -d

4. Verify the server is running: Check the REST API endpoint from your web browser or command line:

   curl http://<server-ip>:3111/agentmemory/health

---

💻 Client Agent Configurations

To connect your coding agents to the centralized server, configure their MCP or CLI configurations using the following structures.

Client 1: Linux Client

In ~/.gemini/antigravity-cli/mcp_config.json (or ~/.config/Cursor/mcpServer.json depending on your agent):

"mcpServers": {
  "agentmemory": {
    "command": "npx",
    "args": ["-y", "@agentmemory/mcp"],
    "env": {
      "AGENTMEMORY_URL": "http://<server-ip>:3111",
      "AGENTMEMORY_TOOLS": "all",
      "AGENTMEMORY_FORCE_PROXY": "1"
    }
  }
}

Client 2: macOS Client

In /Users/<your-mac-username>/.gemini/antigravity-cli/mcp_config.json (or standard MCP configurations):

"mcpServers": {
  "agentmemory": {
    "command": "<absolute-path-to-npx>",
    "args": ["-y", "@agentmemory/mcp"],
    "env": {
      "PATH": "<path-to-node-bin-directory>:/usr/local/bin:/usr/bin:/bin",
      "AGENTMEMORY_URL": "http://<server-ip>:3111",
      "AGENTMEMORY_TOOLS": "all",
      "AGENTMEMORY_FORCE_PROXY": "1"
    }
  }
}

---

⚠️ Troubleshooting (Common Error Log)

1. Alpine Glibc Library Issue:

   • Error: not found when executing iii in a node:20-alpine base image.
   • Solution: Use the Debian-based node:20-slim image instead.

2. Loopback & Nginx DNS Gateway 502:

   • Error: Nginx failing to resolve the internal port 3113 because it is exposed on loopback in a separate container.
   • Solution: Shared the network namespace using network_mode: "service:agentmemory".

3. WebSockets Stuck on "Connecting":

   • Error: Nginx proxying /stream/mem-live/viewer requests to a path that isn't handled correctly.
   • Solution: Set proxy_pass http://127.0.0.1:3112/; with a trailing slash / to correctly route to the root of the WebSocket server.

4. Homebrew Node Not Found on macOS (env: node: No such file or directory):

   • Error: npx called by the parent app fails because the GUI environment doesn't load the Node path.
   • Solution: Add the absolute path to your Node/npm binary folder (e.g. /opt/homebrew/bin or standard Node installation folder) in the PATH variable inside the MCP configuration.

5. Client Agents Disconnecting or Isolating Memory Context:

   • Error: A client agent saves memory logs locally instead of writing to the central server, leading to fractured context.
   • Solution: Ensure that in the client's MCP configuration (mcp_config.json), "AGENTMEMORY_URL" points explicitly to the Tailscale/LAN IP of the central host (http://<server-ip>:3111) instead of localhost, and that "AGENTMEMORY_FORCE_PROXY": "1" is active.

---

⚖️ Credits & License

• Original Creator: This project is a specialized server-client deployment wrapper of the excellent agentmemory library developed by Rohit Gupta (rohitg00). We are extremely grateful for his work in creating a persistent memory layer for AI agents.
• Server Adaptation & Docker Stack: Packaged and adapted for multi-client centralized server architectures by the juniorbarchini-oss organization.
• License: Distributed under the MIT License. See the LICENSE file for details.

---

🌟 Support & Donations

If you find this deployment stack useful, you can support the project in two ways:

1. Star the Repository: Click the ⭐ button at the top right of this page.
2. Support on Ko-fi: Buy me a coffee to support my work and maintenance of my open-source tools: