English | 简体中文

MindMemOS is an open-source long-term memory system for AI agents and applications. It helps agents turn conversations, files, tool traces, feedback, and offline reflection into searchable, updateable, project-isolated memory.

⭐ GitHub Star automatically upgrades your account to Pro quota membership. Website

Website · FastAPI Docs · PyPI SDK · OpenClaw Plugin · Local Docs

MindMemOS-schema achieves state-of-the-art on LoCoMo, the most competitive benchmark for long-term memory systems, with an overall score of 93.64.

• Benchmark: LoCoMo, the most mainstream and fiercely contested benchmark for long-term memory systems, focused on factual memory retention and joint analysis, covering single-hop, multi-hop, temporal, and open-domain question answering.
• Note: Answer model: gpt-4.1-mini. Baseline metrics are cited from the EverMemOS paper.

Evaluation config: config/mindmemos_eval/memory_evaluation_locomo.example.yaml

cp config/mindmemos_eval/memory_evaluation_locomo.example.yaml config/mindmemos_eval/memory_evaluation_locomo.yaml
# fill in API keys, then run:
uv run python -m mindmemos_eval.cli memory \
  --benchmark-config config/mindmemos_eval/memory_evaluation_locomo.yaml \
  --benchmark-list locomo \
  --algorithm schema \
  --manifest-output output/locomo_manifest.jsonl \
  --api-key-output config/mindmemos/api_keys.yaml

MindMemOS achieves state-of-the-art on PersonaMem through higher-order property modeling and discovery, leading the current SOTA by approximately 2 points in overall accuracy.

• Benchmark: PersonaMem, a persona-centric memory benchmark focused on user profiling and preference understanding, evaluating recall, tracking, revisiting, suggestion, recommendation, and generalization of user traits.
• Note: All results are from local runs of open-source code (memory model and answer model: gpt-4.1-mini).

• Benchmark: MemoryAgentBench, a multi-session agent benchmark measuring Subsequence Exact Match (SubEM) for memory-augmented QA. Compares SubEM performance and memory count changes before and after Dreaming.
• Experiment setting: top-k=50, chunk_size=1024
• Note: MIRIX and mem0 baseline results are from the paper, where chunk_size=4096.

• Portable across agents: Persist user profiles, preferences, project facts, tool experience, and skill candidates as reusable user assets that can move across OpenClaw, Hermes, Claude Code, OpenHands, and other agent frameworks.
• Self-evolving memory: Improve memory quality continuously through schema learning, dreaming, and feedback, so the system can learn frequent memory patterns, consolidate duplicates, and use correction signals to optimize add/search behavior.
• Memory-Skills loop: Turn experience memories into skill candidates, then feed skill execution results, failures, and user feedback back into memory so skills can keep evolving.

• Skills system: Route and govern large, redundant skill libraries, evolve skills from real usage, and synthesize new skills from high-frequency user scenarios through offline simulation and refinement.
• File system memory: Structure scattered knowledge across local files, documents, project artifacts, and agent outputs into managed knowledge objects or graphs, so agents can use the user's file knowledge more reliably to complete tasks.
• Agent integrations: Deeper integrations with coding agents, OpenClaw, Codex-style workflows, and long-running multi-agent systems.

MindMemOS uses uv for dependency management and local command execution.

For detailed configuration instructions, see docs/deploy/instruction.md.

cp .env.example .env
cp config/mindmemos/dev.example.yaml config/mindmemos/dev.yaml

Configure config/mindmemos/api_keys.yaml with an API key and its bound project_id. Public memory APIs use bearer authentication:

Authorization: Bearer <api_key>

Before starting the stack, edit config/mindmemos/dev.yaml and configure at least these model routers:

• chat_model_router: LLM generation and extraction.
• embed_model_router: semantic embedding generation.
• rerank_model_router: reranking for search candidates.

Also make sure database.qdrant.vector_size matches the embedding endpoint dimension.

Start the local stack:

make dev

make dev starts the full Docker dependency stack before FastAPI. To start only core dependencies:

make dev-core          # Qdrant + Neo4j + Kafka
make db-observability  # Qdrant + Neo4j + Kafka + ClickHouse + OTel + Grafana

Docker tier rules:

• make dev-core starts Qdrant, Neo4j, Kafka, Kafka UI, and kafka-exporter.
• make dev and make db-observability start the full Docker dependency stack.
• If telemetry.enabled=true, use the full stack so the OTel collector and ClickHouse endpoint exist; Grafana is only for viewing telemetry.

Default local services:

FastAPI:   http://127.0.0.1:8000
API Docs:  http://127.0.0.1:8000/docs

Call the local API the same way as the hosted FastAPI service: replace the base URL with http://127.0.0.1:8000 and use the API key configured in config/mindmemos/api_keys.yaml.

Stop the local stack:

make dev-down

Use this path when calling the hosted MindMemOS FastAPI service. Apply for an API key from the MindMemOS website: https://mindmemos.cn. Use the issued API key in the Authorization: Bearer <api_key> header.

Add a memory:

curl -X POST https://mindmemos.cn/v1/memory/add \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "u_123",
    "messages": [
      {
        "role": "user",
        "content": "I prefer iced Americano."
      }
    ],
    "mode": "sync"
  }'

Search memories:

curl -X POST https://mindmemos.cn/v1/memory/search \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "u_123",
    "query": "What coffee does the user prefer?",
    "top_k": 5,
    "search_strategy": "fast"
  }'

For local deployment, replace the base URL with http://127.0.0.1:8000.

Skills are versioned SKILL.md bundles that can be attached to memory add traces and later evolved from real usage. Register a skill first:

curl -X POST https://mindmemos.cn/v1/skills/register \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "travel-planner",
    "content": "# Travel Planner\n\nPrefer concise itineraries and surface hotel preferences.",
    "version_label": "v1"
  }'

The response includes cloud_skill_id, version_id, and content_hash. List or inspect managed skills:

curl -X GET https://mindmemos.cn/v1/skills \
  -H "Authorization: Bearer <api_key>"

curl -X POST https://mindmemos.cn/v1/skills/<cloud_skill_id>/get \
  -H "Authorization: Bearer <api_key>"

When writing task traces, pass lightweight skill_context references in /v1/memory/add; do not include full skill content there:

curl -X POST https://mindmemos.cn/v1/memory/add \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "u_123",
    "messages": [
      {
        "role": "user",
        "content": "Plan a two-day Guangzhou trip."
      }
    ],
    "skill_context": [
      {
        "name": "travel-planner",
        "content_hash": "<content_hash>",
        "base_version_id": "<version_id>",
        "usage": "injected"
      }
    ],
    "mode": "sync"
  }'

The Python SDK exposes the same flow through MindMemOSClient.skills; registered local skills can be pushed, pulled, synced, updated, rolled back, and used by client.memory.add(...) automatically when skill detection is enabled.

The Python SDK is available on PyPI: mindmemos-sdk.

Configure credentials once:

uv run mindmemos auth

Then reuse the local SDK config:

import time

from mindmemos_sdk import MindMemOSClient
from mindmemos_sdk.memory import DialogueMessage

with MindMemOSClient() as client:
    add_result = client.memory.add(
        messages=[
            DialogueMessage(
                role="user",
                content="I prefer iced Americano.",
                timestamp=int(time.time() * 1000),
            )
        ]
    )
    for item in add_result.memories:
        print(item.operation, item.memory_id, item.content)

    search_result = client.memory.search("coffee preference", top_k=5)
    for hit in search_result.memories:
        print(hit.id, hit.memory)

Or pass credentials explicitly:

from mindmemos_sdk import MindMemOSClient
from mindmemos_sdk.memory import DialogueMessage

client = MindMemOSClient(
    base_url="https://mindmemos.cn",
    api_key="mk_xxx",
    user_id="u_123",
)

result = client.memory.add(
    messages=[DialogueMessage(role="user", content="I prefer iced Americano.")]
)
print(result.memories)

client.close()

The CLI is shipped with the Python SDK package.

Configure the CLI:

uv run mindmemos auth

Add and search memories:

uv run mindmemos memory add --content "我喜欢喝冰美式"
uv run mindmemos memory search "咖啡偏好" --top-k 5

Manage memories:

uv run mindmemos memory get --top-k 10
uv run mindmemos memory update <memory_id> --content "我现在更喜欢拿铁"
uv run mindmemos memory delete <memory_id>
uv run mindmemos memory feedback --text "刚才召回的偏好不准确"
uv run mindmemos memory dreaming

The OpenClaw plugin is available on npm: @mindmemos/openclaw-plugin. It searches MindMemOS before each prompt and injects relevant memories as context, then stores completed OpenClaw conversations through the mindmemos CLI.

Authenticate the CLI first:

uv run mindmemos auth

Then install and enable the plugin in OpenClaw:

openclaw plugins install @mindmemos/openclaw-plugin
openclaw plugins enable mindmemos-memory

For full configuration and troubleshooting, see docs/sdk/openclaw_plugin.md.

Join the MindMemOS Feishu community for updates, discussions, and support.

MIT License.