Mem0 integration for ElizaOS via Mem0 Platform REST APIs.

This plugin is designed for persistent, cross-session memory: storing important user facts/preferences, retrieving relevant memories at response time, and letting the agent explicitly manage memories (search/update/delete) when needed.

Mem0Service wraps the Mem0 Platform endpoints and handles:

• Auth headers (Authorization: Token <MEM0_API_KEY>)
• Base URL selection (MEM0_BASE_URL, default https://api.mem0.ai)
• “Scope defaults” (how user_id, agent_id, run_id, etc. are chosen when you don’t provide filters explicitly)

Use cases:

• Centralize Mem0 calls for other plugins/actions/providers.
• Standardize your memory partitioning across multiple agents and platforms.
• Avoid repeating boilerplate headers/base URL and filter logic.

The provider runs on each message and:

• Uses the incoming message text as the Mem0 search query.
• Applies default scope filters (based on MEM0_SCOPE_MODE, IDs, and optional run_id).
• Injects a short, bullet list of memories into the prompt context.

Use cases:

• “Long-term memory” recall for personalization (“You’re vegetarian”, “You prefer TypeScript”, “Your project is called X”).
• Prevent the agent from re-asking questions across sessions.
• Turn chat history into structured, searchable memories without stuffing the whole transcript into the prompt.

Actions expose Mem0 operations so the agent can deliberately manage memory:

• MEM0_ADD_MEMORIES
• MEM0_SEARCH_MEMORIES
• MEM0_GET_MEMORIES
• MEM0_GET_MEMORY
• MEM0_UPDATE_MEMORY
• MEM0_DELETE_MEMORY

Use cases:

• “Remember this forever” UX: the agent calls MEM0_ADD_MEMORIES.
• “What did I say about …?”: the agent calls MEM0_SEARCH_MEMORIES.
• “Forget that / correct that”: the agent calls MEM0_UPDATE_MEMORY or MEM0_DELETE_MEMORY.
• Admin/debug flows: list memories, inspect a single memory record.

If enabled, the plugin listens for EventType.MESSAGE_RECEIVED and automatically adds the raw user message as a Mem0 memory entry.

Use cases:

• “Always-on journaling” style agents.
• Support agents that must retain everything by default.
• Rapid prototyping to validate memory value before you build smarter “what should be saved” logic.

Trade-offs:

• Auto-saving everything can store noise and increase costs/volume. Many teams start with MEM0_AUTO_SAVE=false and rely on explicit actions + provider recall.

• Node.js >= 18
• ElizaOS @elizaos/core >= 1.7.0
• A Mem0 Platform API key (MEM0_API_KEY)

npm install @elizaos/plugin-mem0

1. Add secrets to your .env:

MEM0_API_KEY="m0-..."

2. Register the plugin in your character:

import mem0Plugin from "@elizaos/plugin-mem0";

export const character = {
  name: "eliza",
  plugins: [mem0Plugin],
};

3. Start your agent as usual.

This plugin reads settings from:

1. runtime.getSetting(KEY) (if your ElizaOS project sets runtime settings), then
2. process.env[KEY]

Your Mem0 Platform API key. Without this, the provider and actions will be disabled.

Use this if you have a proxy or alternative Mem0 API endpoint.

Mem0 supports multiple “identity dimensions” (from Mem0 docs):

• user_id – who the memory belongs to (person/account)
• agent_id – which agent persona/tool it belongs to
• run_id – a temporary session / thread / ticket / conversation ID
• plus app_id, project_id, org_id for multi-tenant setups

This plugin picks defaults so you can start without custom filter logic.

Controls where memories are read from by default and which IDs are sent on writes:

• user: treat memory as belonging to the user (best for personalization)
• agent: treat memory as belonging to the agent persona (best for “character memory” / brand voice)
• both: write to both scopes (user + agent) and read with an OR filter

Use cases:

• user: “Remember my preferences across all agents/sessions.”
• agent: “Remember the agent’s policy, tools, operating procedure, tone.”
• both: “Remember both user preferences and agent persona facts.”

Important note from Mem0 docs:

• Combining user_id and agent_id with an AND filter can return empty results depending on how the platform stores records. This plugin’s both mode reads with an OR filter by default to avoid that common pitfall.

Override the default user_id used by this plugin.

Use cases:

• Map multiple platform IDs (Discord, Telegram, web) to a single canonical user ID.
• Force all memory into a single shared “user” for demo/testing.

Override the default agent_id used by this plugin.

Use cases:

• Multiple Eliza agents share a single Mem0 agent persona scope.
• You want Mem0 agent_id to be a stable string (not a UUID).

If true, this plugin sets run_id = message.roomId automatically.

Use cases:

• Per-room or per-channel memory partitioning (“each Discord channel is a separate memory thread”).
• Support inbox tickets: bind memory to a ticket room so it expires/clears independently.

Trade-off:

• If you want cross-room recall, keep this false and rely on user_id scope instead.

These fields are added to writes (and included in default read filters) if set:

• MEM0_APP_ID
• MEM0_PROJECT_ID
• MEM0_ORG_ID

Use cases:

• White-label deployments: keep memories separated per partner app.
• Multiple projects share infrastructure but must not share memory data.

How many memories the mem0 provider requests from Mem0 for each message.

Use cases:

• Lower for cost/latency sensitivity.
• Higher for complex tasks where long-term memory is critical (coaching, tutoring, long-running projects).

If true, every incoming message triggers a Mem0 addMemories call with:

• messages: [{ role: "user", content: <incoming text> }]
• default IDs and scoping derived from config

Use cases:

• Journaling agents.
• Agents where “everything is valuable” (some support/CRM flows).

Trade-offs:

• Higher volume, more noise, more cost.
• Often better: keep auto-save off and let the agent decide when to store via MEM0_ADD_MEMORIES.

On each message, the provider:

1. Uses the message text as a query
2. Calls POST /v2/memories/search/ with default filters
3. Extracts memory strings from the response
4. Returns a ProviderResult that includes:

• text: A prompt-friendly block like:
  • Mem0 memories:
  • - ...
  • - ...
• values.mem0Memories: array of memory strings
• data.mem0Memories: array of memory strings

Use cases:

• Prompt injection for personalization without custom prompt engineering.
• Downstream actions/providers can read state.values.mem0Memories (depending on your runtime/state composition strategy).

Actions accept input via:

• message.content.args / message.content.params / message.content.parameters / message.content.input / message.content.data (object), or
• JSON in message.content.text

Example payload for MEM0_SEARCH_MEMORIES:

{
  "query": "What do you know about me?",
  "filters": { "user_id": "alice" },
  "limit": 5
}

Tip: Most teams standardize on message.content.args = { ... } to avoid JSON parsing ambiguity.

All actions return { success: boolean, data?: { response }, error?: string }.

Adds new memories to Mem0 (POST /v1/memories/).

Default behavior:

• If you don’t provide messages, it stores the current user message text as a single turn.
• It applies default scoping (MEM0_SCOPE_MODE, IDs, and optional run_id).

Common use cases:

• “Remember this” button/command.
• Store structured facts: set metadata with a category/tag.
• Force synchronous processing: set async_mode: false (if your workflow needs immediate results).

Example:

{
  "messages": [
    { "role": "user", "content": "I'm allergic to peanuts." },
    { "role": "assistant", "content": "Got it. I will remember that." }
  ],
  "metadata": { "category": "health" }
}

Searches memories by semantic query (POST /v2/memories/search/).

Default behavior:

• If you don’t provide query, it uses the current user message text.
• If you don’t provide filters, it uses default scope filters.

Common use cases:

• Retrieve preferences before answering (“Any dietary restrictions?”).
• Tool routing (“Which project did we discuss last week?”).
• Debug memory quality by searching for “facts about X”.

Example:

{
  "query": "dietary restrictions",
  "filters": { "user_id": "alice" },
  "limit": 10
}

Lists memories via the v2 “get all” endpoint (POST /v2/memories/).

Common use cases:

• Build admin UIs.
• Periodic audits (“show me everything stored for this user”).
• Export pipelines (combined with Mem0 export endpoints in your own tooling).

Example:

{
  "filters": {
    "AND": [
      { "user_id": "alice" },
      { "created_at": { "gte": "2025-01-01" } }
    ]
  },
  "limit": 50,
  "offset": 0
}

Fetches a single memory by ID (GET /v1/memories/{memory_id}/).

Use cases:

• Inspect a specific memory from a search result.
• Show a user exactly what’s stored before updating/deleting it.

Example:

{ "memory_id": "mem_..." }

Updates a memory by ID (PUT /v1/memories/{memory_id}/).

Use cases:

• Correct outdated facts (“I moved to NYC, not Austin.”).
• Normalize phrasing for cleaner future retrieval.
• Attach/adjust metadata (depending on Mem0 API behavior).

Example:

{
  "memory_id": "mem_...",
  "memory": "User moved to NYC in 2025.",
  "metadata": { "category": "profile" }
}

Deletes a memory by ID (DELETE /v1/memories/{memory_id}/).

Use cases:

• “Forget that” requests.
• Removing incorrect or sensitive information.

Example:

{ "memory_id": "mem_..." }

Config:

• MEM0_SCOPE_MODE=user
• MEM0_AUTO_SAVE=false

Behavior:

• Provider recalls user preferences automatically.
• Agent calls MEM0_ADD_MEMORIES only when the user explicitly asks (“remember this”) or when the agent detects a durable preference/fact.

Config:

• MEM0_SCOPE_MODE=agent
• optionally set MEM0_AGENT_ID="brand_voice" so the persona is stable across deployments

Behavior:

• Mem0 stores and retrieves “agent memory” (style guide, policies, operating procedures).

Config:

• MEM0_USE_ROOM_ID_AS_RUN_ID=true
• scope mode can be user (user’s thread history) or agent (agent’s thread memory)

Behavior:

• Each room/ticket becomes its own short-lived memory partition.

Config:

• MEM0_APP_ID, MEM0_PROJECT_ID, MEM0_ORG_ID set appropriately

Behavior:

• Prevents accidental memory mixing across tenants/apps/projects.

• Ensure MEM0_API_KEY is set.
• Check logs for mem0Provider failed / mem0 auto-save failed.

• Your Mem0 API key may be invalid or revoked.
• Confirm you’re using MEM0_API_KEY from your Mem0 dashboard.

Common causes:

• Scope mismatch: you wrote with user_id but you’re searching with agent_id (or vice versa).
• You set MEM0_USE_ROOM_ID_AS_RUN_ID=true, so searches are scoped to a room-specific run_id.
• You are combining entity dimensions in a way that yields no results (see MEM0_SCOPE_MODE=both notes).

• Set MEM0_AUTO_SAVE=false.
• Prefer explicit saving with MEM0_ADD_MEMORIES and metadata categories.

• Treat MEM0_API_KEY as a secret; do not commit it. This repo includes .env.example and .gitignore ignores .env.
• When using Mem0 Platform, message content sent to Mem0 is transmitted to the Mem0 API for processing and storage. Review Mem0’s privacy/security docs for your compliance needs.

This plugin follows Mem0’s documented endpoints and headers:

• Add memories: POST /v1/memories/
• Search memories: POST /v2/memories/search/
• List memories: POST /v2/memories/
• Get/update/delete: /v1/memories/{memory_id}/

Docs starting points:

• https://docs.mem0.ai/introduction
• https://docs.mem0.ai/api-reference/memory/add-memories

npm install
npm run typecheck
npm run build