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

> Learn how to set up a standalone agentmemory MCP server using environment variables and a simple command. This guide details its in-memory store with JSON persistence, removing the need for a remote engine.

- Repository: [Rohit Ghumare/agentmemory](https://github.com/rohitg00/agentmemory)
- Tags: how-to-guide
- Published: 2026-05-10

---

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

```bash
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`](https://github.com/rohitg00/agentmemory/blob/main/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:

```bash
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`](https://github.com/rohitg00/agentmemory/blob/main/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:

```bash
node dist/standalone.mjs

```

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

```bash
npx agentmemory

```

Upon startup, the server writes a diagnostic banner to stderr. According to the implementation in [`src/mcp/standalone.ts`](https://github.com/rohitg00/agentmemory/blob/main/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`](https://github.com/rohitg00/agentmemory/blob/main/src/config.ts)
- Registers MCP tools filtered from [`src/mcp/tools-registry.ts`](https://github.com/rohitg00/agentmemory/blob/main/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`](https://github.com/rohitg00/agentmemory/blob/main/src/mcp/tools-registry.ts) and implemented through [`src/mcp/server.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/mcp/server.ts).

### Save a Memory

```json
{
  "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

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

```

### Smart Search

```json
{
  "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:

```bash
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`](https://github.com/rohitg00/agentmemory/blob/main/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`](https://github.com/rohitg00/agentmemory/blob/main/src/mcp/standalone.ts)**: The primary entry point that orchestrates the standalone server lifecycle, transport creation, and graceful shutdown handling.

- **[`src/config.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/config.ts)**: Detects the `STANDALONE_MCP` environment flag and resolves the `STANDALONE_PERSIST_PATH` location.

- **[`src/mcp/tools-registry.ts`](https://github.com/rohitg00/agentmemory/blob/main/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`](https://github.com/rohitg00/agentmemory/blob/main/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`](https://github.com/rohitg00/agentmemory/blob/main/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`](https://github.com/rohitg00/agentmemory/blob/main/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`](https://github.com/rohitg00/agentmemory/blob/main/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`](https://github.com/rohitg00/agentmemory/blob/main/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.