# How to Migrate Memories from mem0 or Letta to AgentMemory: A Complete Guide

> Easily migrate memories from mem0 or Letta to AgentMemory using the built-in export/import pipeline. Learn how to perform a seamless migration via CLI, REST API, or MCP tools.

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

---

**AgentMemory provides a built-in export/import pipeline that consumes JSON exports from mem0 or Letta through the `mem::import` function, enabling seamless migration via CLI, REST API, or MCP tools.**

Migrating conversational memory between AI agent frameworks shouldn't require manual data transformation. The `rohitg00/agentmemory` repository includes a robust import system that accepts standardized JSON exports from mem0 and Letta, automatically validating and ingesting sessions, observations, and knowledge graphs into its SQLite-backed store.

## Understanding the Export/Import Architecture

The migration logic resides in [`src/functions/export-import.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/functions/export-import.ts), which defines two primary SDK functions: `mem::export` and `mem::import`. According to the AgentMemory source code, the import routine expects an `ExportData` object containing a top-level `version` string, `exportedAt` timestamp, and nested arrays for sessions, observations, memories, profiles, and graph nodes/edges.

The validator checks the `version` field against an internal `supportedVersions` array (lines 179-180 of [`export-import.ts`](https://github.com/rohitg00/agentmemory/blob/main/export-import.ts)) to ensure compatibility. Supported versions range from `0.3.0` to `0.9.5`, covering recent export formats from both mem0 and Letta. If the version is missing or unsupported, the import fails before any data writes occur.

## Step-by-Step Migration Process

The migration follows a three-phase pipeline that preserves data integrity while respecting storage limits.

### Step 1: Export from mem0 or Letta

Generate a JSON export using the native export commands of your source system. Both mem0 and Letta produce JSON or JSON-L files containing memory objects, though you must ensure the output includes a `version` field at the root level.

### Step 2: Validate the Export Format

Before importing, verify your export matches the `ExportData` interface defined in [`src/types.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/types.ts). The file must contain:

- A `version` string (e.g., `"0.9.5"`)
- An `exportedAt` ISO timestamp
- Arrays for `sessions`, `observations`, `memories`, and optional graph data

If your mem0 or Letta export lacks the `version` field, add it manually to satisfy the validator in [`export-import.ts`](https://github.com/rohitg00/agentmemory/blob/main/export-import.ts).

### Step 3: Import into AgentMemory

Invoke the `mem::import` function through your preferred interface. The function supports three write strategies:

- **merge**: Updates existing records and inserts new ones
- **replace**: Deletes existing data before import
- **skip**: Ignores conflicts without modifying existing records

During processing, the importer enforces caps defined by `MAX_SESSIONS`, `MAX_MEMORIES`, and related constants to prevent runaway imports (lines 386-640).

## Import Methods and Interfaces

AgentMemory exposes the migration capability through multiple interfaces, allowing integration into existing DevOps pipelines or ad-hoc CLI usage.

### CLI Migration

The command-line interface in [`src/cli.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/cli.ts) wraps the SDK functions into simple commands:

```bash

# Export current AgentMemory state (for reference)

agentmemory export > reference-backup.json

# Import a Letta or mem0 export file

agentmemory import --payload @letta-export.json

```

The `--payload` flag accepts file paths using the `@` prefix or inline JSON strings.

### REST API Endpoint

The HTTP server defined in [`src/triggers/api.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/triggers/api.ts) exposes a POST endpoint at `/agentmemory/import` (lines 933-940) that proxies directly to the `mem::import` function:

```bash
curl -X POST http://localhost:3111/agentmemory/import \
  -H "Content-Type: application/json" \
  -d @mem0-export.json

```

This endpoint validates the request body and returns the import result, making it suitable for automated migration scripts.

### Direct SDK Integration

For programmatic migrations, instantiate the SDK and trigger the import directly:

```typescript
import { createSdk } from "iii-sdk";
import { readFileSync } from "node:fs";

const sdk = await createSdk({ /* engine config */ });
const exportData = JSON.parse(readFileSync("letta-export.json", "utf-8"));

await sdk.trigger({
  function_id: "mem::import",
  payload: { 
    exportData, 
    strategy: "merge" 
  },
});

```

This method provides the most control over error handling and retry logic.

### MCP Tool Support

The Model Context Protocol (MCP) server implementation in [`src/mcp/server.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/mcp/server.ts) registers `memory_export` and `memory_import` tools. These enable TCP-based clients to perform migrations without HTTP overhead:

```typescript
// MCP client invocation example
await mcpClient.call("memory_import", {
  exportData: lettaData,
  strategy: "merge"
});

```

## Import Strategies and Safety Limits

The `mem::import` implementation enforces strict resource guards to protect the target instance. According to [`src/functions/export-import.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/functions/export-import.ts), the system checks against `MAX_SESSIONS`, `MAX_MEMORIES`, and related caps before writing any records. If your export exceeds these limits, the import fails with a descriptive error before partial data commits occur.

Choose your strategy based on your migration scenario:

- **merge**: Use for incremental updates or syncing multiple sources
- **replace**: Use for complete system cutovers
- **skip**: Use for dry-runs or when preserving target data is critical

## Audit Trail and Version Compatibility

Every import operation records an audit entry via the `recordAudit` function (line 31 of [`export-import.ts`](https://github.com/rohitg00/agentmemory/blob/main/export-import.ts)), creating a traceable log of when the migration occurred and which version schema was used. This audit trail persists in the SQLite store alongside your memories, enabling compliance verification and rollback planning.

The version validator accepts strings from `0.3.0` through `0.9.5`. If your mem0 or Letta export uses an older format, you may need to transform the JSON to include the required `version` field before AgentMemory will process it.

## Summary

- AgentMemory's `mem::import` function in [`src/functions/export-import.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/functions/export-import.ts) accepts JSON exports from mem0 and Letta without code changes
- The import requires a `version` field in the export data and supports strategies: **merge**, **replace**, and **skip**
- Access the migration via CLI (`agentmemory import`), REST API (`POST /agentmemory/import`), direct SDK calls, or MCP tools
- Built-in size limits (`MAX_SESSIONS`, `MAX_MEMORIES`) prevent overloading the target SQLite store
- All imports generate audit entries for traceability

## Frequently Asked Questions

### What file formats does AgentMemory accept for memory imports?

AgentMemory accepts JSON and JSON-L files conforming to the `ExportData` interface defined in [`src/types.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/types.ts). The import system specifically requires a top-level `version` string and standardizes on the schema used internally by the `mem::export` function. While mem0 and Letta export native JSON, you must ensure the presence of the `version` field to pass validation in [`src/functions/export-import.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/functions/export-import.ts).

### How does AgentMemory handle conflicts when importing existing memories?

The `mem::import` function accepts a `strategy` parameter that controls conflict resolution. Setting `strategy: "merge"` updates existing records with new data while preserving untouched entities, `strategy: "replace"` wipes existing data before import, and `strategy: "skip"` ignores any conflicting records without modification. This logic is implemented in the write loop starting at line 386 of [`src/functions/export-import.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/functions/export-import.ts).

### What are the size limits for memory imports?

The import routine enforces hard caps defined as `MAX_SESSIONS`, `MAX_MEMORIES`, and related constants before writing to the SQLite store. These limits prevent runaway imports from consuming excessive disk space or memory. If your export exceeds these thresholds, the import fails immediately with a validation error before any data commits occur.

### Can I migrate memories incrementally from mem0 or Letta?

Yes. Use the `merge` strategy when calling `mem::import` to perform incremental migrations. This approach updates existing records with new information and inserts only new entities, making it safe to run repeatedly during a phased migration. The audit logging system in [`export-import.ts`](https://github.com/rohitg00/agentmemory/blob/main/export-import.ts) tracks each incremental import separately for compliance monitoring.