How to Set Up a Standalone AgentMemory MCP Server: Complete Configuration Guide

Set the STANDALONE_MCP=true environment variable and run node dist/standalone.mjs to boot a self-contained MCP server that uses an in-memory key-value store with JSON file persistence, eliminating the need for a remote iii-engine process.

The AgentMemory project provides a standalone mode for its MCP (Memory Control Protocol) server that operates independently without requiring a remote iii-engine process. By running the compiled entry point in standalone mode, you create a local Stdio-based transport backed by an InMemoryKV store that persists to disk on shutdown. This guide covers the complete setup process using the rohitg00/agentmemory repository, from environment configuration to interacting with memory tools via JSON-RPC over standard I/O.

Prerequisites

To run a standalone agentmemory MCP server, you need:

• Node.js version 20 or higher
• npm or yarn package manager
• Git (for cloning the repository)

Installation and Build Process

First, clone the repository and install dependencies. The build process compiles TypeScript to JavaScript using tsdown, generating the dist/standalone.mjs file that serves as the entry point.

git clone https://github.com/rohitg00/agentmemory.git
cd agentmemory
npm ci
npm run build

The npm run build command generates the dist/ directory containing standalone.mjs, which is the compiled output of src/mcp/standalone.ts.

Environment Configuration

Standalone mode requires specific environment variables to activate the local storage backend. Create a .env file in your project root or export these variables in your shell:

export STANDALONE_MCP=true
export STANDALONE_PERSIST_PATH="$HOME/.agentmemory/standalone.json"

The STANDALONE_MCP flag triggers the standalone initialization logic in src/config.ts, which resolves the persistence path and disables remote proxying. The STANDALONE_PERSIST_PATH variable determines where the in-memory store serializes on exit, defaulting to ~/.agentmemory/standalone.json if not specified.

Starting the Standalone Server

Launch the server by executing the compiled module directly:

node dist/standalone.mjs

Alternatively, if you have linked the package globally or installed via npx:

npx agentmemory

Upon startup, the server writes a diagnostic banner to stderr. According to the implementation in src/mcp/standalone.ts, the initialization sequence performs the following actions:

• Creates an InMemoryKV instance for local storage
• Reads STANDALONE_PERSIST_PATH from src/config.ts
• Registers MCP tools filtered from src/mcp/tools-registry.ts
• Starts a Stdio transport for JSON-RPC communication
• Attaches SIGINT and SIGTERM handlers to ensure data persistence on shutdown

You will see output indicating whether the server is proxying to a remote AgentMemory server (via AGENTMEMORY_URL) or falling back to the local KV store.

Interacting with MCP Tools

The standalone server exposes the same tool interface as the networked version, accessible via JSON-RPC over stdin/stdout. The available tools include memory_save, memory_recall, and memory_smart_search, defined in src/mcp/tools-registry.ts and implemented through src/mcp/server.ts.

Save a Memory

{
  "method": "tools/call",
  "params": {
    "name": "memory_save",
    "arguments": {
      "content": "The quick brown fox jumps over the lazy dog.",
      "type": "fact",
      "concepts": "fox, dog",
      "files": "example.txt"
    }
  }
}

Recall Memories

{
  "method": "tools/call",
  "params": {
    "name": "memory_recall",
    "arguments": {
      "query": "fox",
      "limit": 5
    }
  }
}

Smart Search

{
  "method": "tools/call",
  "params": {
    "name": "memory_smart_search",
    "arguments": {
      "query": "lazy dog",
      "limit": 3
    }
  }
}

Testing via Command Line

You can pipe JSON directly into the server for quick testing:

echo '{"method":"tools/list","params":{}}' | node dist/standalone.mjs

This returns the list of implemented tools in the MCP protocol format.

Data Persistence and Storage

The InMemoryKV store maintains all data in memory during operation for high-speed access. On graceful shutdown (SIGINT or SIGTERM), src/mcp/standalone.ts automatically serializes the entire store to the JSON file specified by STANDALONE_PERSIST_PATH. When the server restarts, it checks for the existence of this file and reloads the state, restoring all memories, sessions, and embeddings from the previous session.

Key Implementation Files

Understanding the source structure helps with debugging and advanced configuration:

• src/mcp/standalone.ts: The primary entry point that orchestrates the standalone server lifecycle, transport creation, and graceful shutdown handling.

• src/config.ts: Detects the STANDALONE_MCP environment flag and resolves the STANDALONE_PERSIST_PATH location.

• src/mcp/tools-registry.ts: Contains the complete list of MCP tool definitions; the standalone server filters this registry to expose only the tools it implements locally.

• src/mcp/server.ts: Defines the HTTP-style MCP endpoint handlers that process JSON-RPC requests received through the Stdio transport.

• src/mcp/rest-proxy.ts: Contains the logic that checks AGENTMEMORY_URL and determines whether to proxy requests to a remote server or handle them via the local InMemoryKV instance.

Summary

• Enable standalone mode by setting STANDALONE_MCP=true to run without external dependencies
• Build the project using npm run build to generate dist/standalone.mjs
• Configure persistence with STANDALONE_PERSIST_PATH to customize where JSON data is stored
• Communicate via JSON-RPC over stdin/stdout using MCP tools like memory_save and memory_recall
• Data survives restarts through automatic serialization to disk on graceful shutdown

Frequently Asked Questions

What distinguishes standalone mode from proxy mode?

In standalone mode, the server uses a local InMemoryKV store and does not require a running iii-engine process. In proxy mode (triggered when AGENTMEMORY_URL is set and STANDALONE_MCP is falsy), the server forwards all MCP tool calls to a remote AgentMemory instance via src/mcp/rest-proxy.ts.

Where is memory data stored when using standalone mode?

By default, data persists to ~/.agentmemory/standalone.json as determined by src/config.ts. You can override this location by setting the STANDALONE_PERSIST_PATH environment variable to any absolute file path before starting the server.

Can I run the standalone server without compiling TypeScript?

No, you must run npm run build first to generate the dist/standalone.mjs file from src/mcp/standalone.ts. The server requires Node.js to execute the compiled JavaScript, as the raw TypeScript source contains import statements and type annotations that Node cannot interpret directly.

How do I verify the server is functioning correctly?

Send a tools/list request via stdin or use an MCP client library like iii-sdk to connect via Stdio transport. A functioning server returns a JSON response listing available tools such as memory_save and memory_smart_search, and writes initialization messages to stderr indicating whether it is using local storage or proxying to a remote endpoint.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}