mindmemos

⭐ Star us on GitHub to automatically upgrade to a Pro quota membership.

📰 News

• 2026-08-18: We released the DeepSeek Harness Plugin, letting DeepSeek Harness (dsh) agents automatically recall and write MindMemOS memories.
• 2026-08-14: We released the MindMemOS 1.0 technical report, MindMemOS: A Portable and Self-Evolving Memory Operating Layer for AI Agents.
• 2026-07-17: MindMemOS integrated with LLM4AD_NEXT, providing searchable long-term memory for algorithm design tasks and enabling the accumulation and reuse of cross-task experience, domain knowledge, and constraints.
• 2026-06-30: MindMemOS was officially released!

🌟 Core Features

• Portable across agents: Persist user profiles, preferences, project facts, tool experience, and skill candidates as reusable assets, allowing OpenClaw, Hermes, Claude Code, OpenHands, and other agents to share or transfer the same long-term memory.
• Self-evolving memory system: Continuously improve memory quality through schema learning, dreaming, and feedback by automatically learning frequent memory patterns, consolidating memories offline, and using interaction corrections to optimize add/search workflows.
• Memory and Skills integration: Experience memories can be distilled into skill candidates, while skill execution results, failure traces, and user feedback flow back into the memory system to drive continuous skill evolution.
• Plugin integrations: Connect MindMemOS to different agents and workflows through plugins that retrieve and inject relevant memories before interactions and automatically write conversations back afterward. The OpenClaw Plugin and DeepSeek Harness Plugin are currently available, with more integrations in progress.

🚀 Quick Start

MindMemOS offers two deployment modes (official cloud service, local self-hosting) and three access methods (HTTP API, Python SDK / CLI, agent plugin). Any combination works — server and client speak the same protocol:

Access Method	Use Case	Cloud base_url	Local base_url
HTTP API	Call directly from business apps	https://mindmemos.cn	http://127.0.0.1:8000
Python SDK / CLI	Integrate into business apps	https://mindmemos.cn	http://127.0.0.1:8000
OpenClaw Plugin	Agent auto-recalls / writes memory	https://mindmemos.cn	http://127.0.0.1:8000
DeepSeek Harness Plugin	Agent auto-recalls / writes memory (dsh)	https://mindmemos.cn	http://127.0.0.1:8000

To try it without deploying, use the official cloud service (request an API key on the website); for on-premises or offline use, start with Local Deployment below.

1. Local Deployment

MindMemOS uses uv to manage dependencies and run local commands. For detailed configuration instructions, see docs/deploy/instruction.md.

1.1 Prepare Configuration Files

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

Before startup, configure at least the following three model routers in config/mindmemos/dev.yaml:

• chat_model_router: supports memory extraction, Skill evolution, and other generation tasks.
• embed_model_router: generates semantic embeddings; make sure its dimensions match the Qdrant dimension configuration.
• rerank_model_router: optional; reranks memory retrieval results.

The schema memory-extraction flow is versioned: algo_config.add.schema.version defaults to v2 (rule-based graph fusion) and can be pinned to v1 (develop-compatible flow) per project. Storage is compatible in both directions; see the deployment guide for binding and effective timing.

Configure an API key and its bound project_id in config/mindmemos/api_keys.yaml.

1.2 Start the Service

Start the local service:

make dev

make dev starts the full Docker dependency stack before starting FastAPI.

To start only core dependencies:

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

The default local service port is 8000:

FastAPI:   http://127.0.0.1:8000

Stop the local service:

make dev-down

2. Access Methods

Cloud and local self-hosting use the same access protocol. Local keys come from config/mindmemos/api_keys.yaml; cloud keys are obtained from the website.

2.1 HTTP API

HTTP is the base access method — the SDK and plugins also talk HTTP underneath. Once the service is up, first use curl to verify the endpoints work, then wire up your business logic. Define the address and key before calling (pick local or cloud):

export BASE_URL=http://127.0.0.1:8000   # Local self-host; change to https://mindmemos.cn for cloud
export API_KEY=dev-api-key-001          # Local example key; use a website-issued key for cloud

Add a memory:

curl -sS -X POST "$BASE_URL/v1/memory/add" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "u_123",
    "messages": [{"role": "user", "content": "I like iced Americanos."}]
  }'

Search memories:

curl -sS -X POST "$BASE_URL/v1/memory/search" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "What kind of coffee does the user like?", "top_k": 3}'

A code of ok with readable memory content means the access works. curl is just a smoke-test helper; the shown format is for bash. Other environments / languages and the remaining endpoints (get / list / delete / update / feedback / dreaming / skills, etc.) are all covered in the API docs.

2.2 Configure the SDK

Install the Python SDK:

pip install mindmemos-sdk

Run the authentication command and configure the service address, API key, and default user when prompted:

mindmemos auth

Setting	Local Service	Cloud Service
base_url	http://127.0.0.1:8000	https://mindmemos.cn
api_key	An enabled API key from config/mindmemos/api_keys.yaml	An API key obtained from the MindMemOS website
user_id	A stable identifier for the current end user, such as u_123	A stable identifier for the current end user, such as u_123

The configuration is saved to ~/.mindmemos/settings.json. Check the current configuration with:

mindmemos config show

The local service automatically determines the project_id and memory algorithm from the API key, so SDK calls do not need to pass project_id. The user_id distinguishes users within the same project and can be overridden in an individual add or search call.

If you prefer not to use the local configuration file, pass connection parameters explicitly when creating the client:

from mindmemos_sdk import MindMemOSClient

with MindMemOSClient(
    base_url="http://127.0.0.1:8000",
    api_key="<api_key>",
    user_id="u_123",
) as client:
    ...

Explicit parameters take precedence over values in ~/.mindmemos/settings.json.

2.3 Add and Search Memories with the SDK

After completing the configuration above, MindMemOSClient() automatically reads the service address, API key, and default user_id. The SDK adds the authentication header automatically, so there is no need to construct HTTP requests manually:

from mindmemos_sdk import DialogueMessage, MindMemOSClient

with MindMemOSClient() as client:
    add_result = client.memory.add(
        messages=[
            DialogueMessage(
                role="user",
                content="I like iced Americanos.",
            )
        ],
        mode="sync",
    )

    for item in add_result.memories:
        print(item.operation, item.memory_id, item.content)

    search_result = client.memory.search(
        "What kind of coffee does the user like?",
        top_k=5,
        search_strategy="fast",
        # token_budget=2000,  # optional: strict token budget (enables retention)
    )

    for memory in search_result.memories:
        print(memory.id, memory.memory)

Trigger cloud evolution for a registered Skill:

from mindmemos_sdk import MindMemOSClient

with MindMemOSClient() as client:
    result = client.skills.evolve("my-skill", mode="sync")

    print("evolved:", result.evolved)
    print("pending:", result.pending_count)
    print("threshold:", result.threshold)
    print("new versions:", result.new_version_ids)

Local and cloud services use the same SDK call pattern. To switch between them, reconfigure only the base_url and corresponding API key.

2.4 Use the CLI

After running mindmemos auth, you can also add and search memories directly with the CLI included in the SDK:

mindmemos memory add --content "I like iced Americanos"
mindmemos memory search "coffee preferences" --top-k 5