Long-term Memory (Agent Memory)

Mem0 API compatibility

Projects already using Mem0 can switch to Context0 directly without changing any code. Context0 is fully compatible with all 7 Mem0 v1 endpoints (add, get, update, delete, search, and clear operations on /v1/memories). The only difference: DELETE /v1/memories corresponds to DELETE /v1/memories/clear.

Context0 also provides V3 enhanced endpoints, compatible with the Mem0 v1.1 SDK:

Three-tier memory model

After a conversation is ingested, Context0 automatically performs a three-tier distillation. You can think of it this way: L2 is a voice recorder (capturing everything in full), L1 is a notebook (extracting the key information), and L0 is a personal profile (understanding a person from a single page).

The data flow of the three-tier distillation is as follows:

Conversation ingest ──► L2 Raw Conversations ──LLM extraction──► L1 Atomic Facts ──Entity recognition──► L0 Entity Profile Card
           (immutable, traceable)          (single facts, time-windowed)       (structured entity card)

Token economics: 1,000 accumulated conversation turns from one user (about 30K tokens) are compressed, after two rounds of distillation, into an L0 profile of about 0.75K tokens — a far higher information density than scattered raw conversations.

Memory scopes

Every memory belongs to a scope. The scope determines the visibility and lifecycle of the memory:

Memory lifecycle

A memory goes through the following stages from ingest to evolution:

Ingest → Async distillation (L2→L1→L0) → Retrieval and recall → Hotness decay / invalidation → Dream nightly evolution

Write memories

curl -X POST "$HOST/v1/context/ingest" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_001",
    "user_id": "user_001",
    "messages": [
      {"role": "user", "content": "The project prefers TypeScript; use Prisma as the ORM"},
      {"role": "assistant", "content": "OK, the tech stack choice has been recorded"}
    ]
  }'

curl -X POST "$HOST/v1/memories" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Use NextAuth for the authentication approach"}
    ],
    "user_id": "user_001",
    "metadata": {"source": "manual"}
  }'

{
  "results": [
    {
      "id": "mem_124",
      "memory": "Use NextAuth for the authentication approach",
      "subject": "authentication",
      "validity": "durable",
      "event": "ADD"
    }
  ]
}

Search memories

• Semantic search: POST /v1/memories/search (available in three versions: V1, V2, and V3).

  curl -X POST "$HOST/v2/memories/search" \
    -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
    -d '{
      "query": "tech stack choices",
      "user_id": "user_001",
      "limit": 10
    }'

  Parameter	Required	Description
  query	Yes	Query text. Relevant memories are matched semantically
  user_id	No	Restricts results to a user; a User Key is automatically bound to its own user
  limit	No	Number of results to return, [1,200], default 10 (the alias top_k also works)
  cosine_threshold	No	Similarity lower bound, [0,1]. Default 0.2 for V1/V2 and 0.1 for V3
  vector_only	No	When true, only vector recall is used and BM25 is disabled
  filters	No	Additional filters such as time range

  Differences between the three versions:

  Path	L1 facts	L2 source text	Response format
  POST /v1/memories/search	Returned	Not returned	Bare JSON array
  POST /v2/memories/search	Returned	Returned (enabled by default)	Bare JSON array
  POST /v3/memories/search	Returned	Returned	{"results": [...]} envelope

  Note

  V3 endpoints align with the Mem0 v1.1 SDK. Entity parameters such as user_id are recommended to be passed inside the filters map.

• Get a single memory: GET /v1/memories/{id}.

  curl "$HOST/v1/memories/mem_123" -H "X-API-Key: $API_KEY"

Use memories in conversations

curl -X POST "$HOST/v1/context/assemble" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_002",
    "user_id": "user_001",
    "query": "How do I deploy the application?",
    "token_budget": 4000,
    "include_memories": true,
    "recall": {"top_k": 8}
  }'

{
  "code": 0,
  "data": {
    "prompt_blocks": [
      {
        "role": "system",
        "tag": "user_profile",
        "content": "User prefers TypeScript + Prisma; NextAuth for authentication",
        "tokens": 30,
        "sources": []
      },
      {
        "role": "system",
        "tag": "knowledge",
        "content": "Deployment process: 1. Prepare .env ...",
        "tokens": 120,
        "sources": ["runbook.pdf"]
      }
    ]
  }
}

# 1. Search for relevant memories
curl -X POST "$HOST/v1/memories/search" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"query": "tech stack preferences", "user_id": "user_001", "limit": 5}'

# 2. Concatenate the returned memory content into the system prompt and send it to the LLM

Manage memories

Viewing, editing, pinning, invalidating, and gathering statistics on memories are provided by the following endpoints:

• Example: pin a memory:

  curl -X POST "$HOST/v1/memories/mem_123/pin" -H "X-API-Key: $API_KEY"

• Example: invalidate a memory:

  curl -X POST "$HOST/v3/memories/mem_123/invalidate" -H "X-API-Key: $API_KEY"

• Example: edit an L0 entity card:

  curl -X POST "$HOST/v3/entity_cards/card_1_2_alice/edit" \
    -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
    -d '{
      "role": "Senior backend engineer",
      "preferences": ["Java", "Spring Boot"],
      "attributes": {"domain": "distributed databases"}
    }'

Dashboard operations

In addition to APIs, you can also browse, edit, and search memories in the Dashboard:

• On the Memories page of the Dashboard, select the Entities tab to browse all L0 entity cards and edit fields such as role, preferences, and attributes.

• On the Memories page of the Dashboard, select the Search tab. After you enter a query, results are sorted by similarity, with support for time range filtering and feedback (thumbs up or down).

Custom distillation rules

Distillation rules control "what to extract from conversations and how to extract it". You can define the types of content that Context0 focuses on. Priority chain: custom_instructions in the ingest request > member-level rules > workspace default rules > built-in defaults.

• API reference

  • Set a member-level rule (data plane, User Key):

    curl -X PUT "$HOST/v1/memories/distill-prompt" \
      -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
      -d '{
        "custom_prompt": "Focus on extracting tech stack choices and architecture decisions; ignore small talk",
        "enabled": true
      }'

  • Set a workspace-level rule (management plane, Owner Key):

    curl -X PUT "$OPS_HOST/ops/distill-prompt" \
      -H "X-API-Key: $OWNER_KEY" -H "Content-Type: application/json" \
      -d '{
        "custom_prompt": "Extract technical decisions, project conventions, and team standards",
        "enabled": true
      }'

• Dashboard operations

  On the Memories page of the Dashboard, select the Distillation Rules tab to choose members, edit prompts, and view the effective status.

Dream nightly evolution

Dream is the background evolution engine of Context0. It periodically runs the following tasks automatically:

• Preference decay: preferences that have not been recalled for a long time are automatically down-weighted.

• Contradiction detection: conflicting memories on the same topic are found and marked.

• Entity consolidation: L0 Entity Profile Cards are generated or updated by aggregating L1 facts.

Example: manually trigger Dream (Owner Key):

curl -X POST "$HOST/v1/dream/run" \
  -H "X-API-Key: $OWNER_KEY" -H "Content-Type: application/json" \
  -d '{}'

Promote memories to the knowledge base

Memory promotion aggregates high-value memories (L1 facts) under the same topic into a knowledge base document. The generated document is reviewed manually before being stored, after which it is retrieved and cited like any regular document. For an end-to-end scenario walkthrough, see Make your agent understand your business over time.