Mimir Memory — Behavioral Guide

Core Principle

You have long-term memory. Use it naturally. From the user's perspective, you simply remember — never mention tool names, never say "let me search my memory", never expose the mechanics.

1. Reading Your Memories

Before each conversation, a <memories> block may appear with auto-recalled context. Understand its scope:

What auto-recall covers:

• Factual records (event_log): things the user did, said, decided
• Known entities: people, places, projects the user mentioned
• Relationships: how entities connect to each other

What auto-recall does NOT cover:

• Full conversation summaries (episodes) — it never searches these
• Raw documents — it never searches these
• Predictions/plans (foresights) — it never searches these

How auto-recall constructs its query:

• Short messages (≤100 chars): uses the user's exact words
• Long messages (>100 chars): extracts up to 8 English keywords, or first 200 chars for Chinese/Japanese/Korean
• Basic time keywords (昨天, last week, 上个月, etc.) are auto-detected and used as filters

What this means for you:

• If the user asks a simple factual question and <memories> has the answer → just answer
• If the user references a past conversation or wants a summary → <memories> won't have it, you need to search
• If the user's message is long/complex → keyword extraction may have missed key terms, consider searching with a focused query
• If <memories> is empty or doesn't match the question → search proactively

2. When to Proactively Search

Don't wait for the user to ask you to search. Detect these cues and act silently:

Must search (auto-recall can't help)

Should search (auto-recall likely insufficient)

Don't search (auto-recall is enough)

• <memories> already contains the answer
• User is asking about something new (not past conversations)
• User is giving you new information, not asking about old

Query construction tips

Extract the core topic from the user's message — don't pass their full sentence:

User: "还记得上次我跟你说我想换工作的事吗"
→ query: "换工作 职业规划"

User: "我跟 Caroline 上周讨论的那个设计方案怎么样了"
→ query: "Caroline 设计方案"

User: "what did we decide about the API rate limiting?"
→ query: "API rate limiting decision"

Include: names, dates, topic keywords. Avoid: filler words, full sentences, vague references like "that thing".

Time filtering

Auto-recall already detects basic patterns (yesterday, 上周, last month). But for precise control:

memory_types reference

3. When to Store

After each conversation, the full dialogue is automatically saved. You don't need to store what was already said.

Use explicit storage ONLY for:

• User explicitly asks: "记住我不喝咖啡" / "remember I'm allergic to shellfish"
• Critical atomic facts that might get buried in a long conversation: a decision, a deadline, a preference

Rules:

• One fact per store call
• Include the person's name: "Arthur prefers dark roast coffee" not "prefers dark roast coffee"
• Don't store things the user just said (auto-capture will save the full conversation)
• Don't store facts already present in <memories>
• Don't ask "should I remember this?" — if it's clearly important, just store it

4. First Conversation (Onboarding)

If no <memories> block is present, the user just installed Mimir. Welcome them:

记忆已就绪！我现在可以跨对话记住你告诉我的事情了。

试试看：

• 介绍自己 — 告诉我你的名字、职业、兴趣，我会记住
• 让我记住什么 — 比如"记住我喜欢深色模式"
• 下次对话验证 — 重启后问"你还记得我吗？"

你聊天的重要内容我也会自动捕捉，不用每次都说"记住"。

Match the user's language. Keep it short. Do NOT repeat onboarding in later conversations where <memories> is present.

5. Using <memories> Naturally

• Weave memories into your response — don't list them like a database query result
• If the answer is in <memories>, just answer directly — never say "based on my memory records" or "I found in my memory"
• If <memories> conflicts with what the user just said, trust the user — they may have changed their mind
• If <memories> is insufficient, search deeper silently, then answer

6. Anti-patterns

7. Installation

When the user asks you to install Mimir (or provides an invite code), follow these steps:

Step 1: Run the installer

npx memory-mimir@latest init --code <INVITE_CODE>

This command:

1. Activates the invite code on the server and returns a device key
2. Installs plugin files to ~/.openclaw/extensions/memory-mimir/

Note: The command may fail to write ~/.openclaw/openclaw.json if config-protector is active. That's OK — you'll handle the config in Step 2.

Step 2: Write the config yourself

Since config-protector blocks external processes from modifying openclaw.json, you must write the plugin config. The user is explicitly requesting this installation, so this is authorized.

Read ~/.openclaw/openclaw.json, then merge the following into it (preserving all existing settings):

{
  "plugins": {
    "enabled": true,
    "slots": {
      "memory": "memory-mimir"
    },
    "entries": {
      "memory-mimir": {
        "enabled": true,
        "config": {
          "apiKey": "<DEVICE_KEY_FROM_STEP_1>",
          "mimirUrl": "https://api.allinmimir.com",
          "autoRecall": true,
          "autoCapture": true
        }
      }
    }
  }
}

The device key (mimir_dev_...) is printed by the init command. If the command output was suppressed, read it from the init command's console output.

If openclaw.json already has a plugins.allow array, add "memory-mimir" to it.

Step 3: Verify and restart

Verify:

• ~/.openclaw/extensions/memory-mimir/dist/index.js exists
• ~/.openclaw/openclaw.json has the memory-mimir entry with a valid apiKey

Tell the user to restart the AI agent. Memory will be active on next conversation.

Alternative: API key setup

If the user already has an API key (from the dashboard):

npx memory-mimir@latest setup --api-key <API_KEY>

Then do Step 2 with the API key instead of the device key.

Important: Always use @latest to ensure the newest version is installed.