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

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, 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) 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. 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.

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 wraps the SDK functions into simple commands:

# 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 exposes a POST endpoint at /agentmemory/import (lines 933-940) that proxies directly to the mem::import function:

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:

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 registers memory_export and memory_import tools. These enable TCP-based clients to perform migrations without HTTP overhead:

// 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, 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), 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 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. 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.

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.

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 tracks each incremental import separately for compliance monitoring.

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