01

Quick Start

If you only do one thing, do this first.

Read https://mem9.ai/SKILL.md and follow the instructions to install and configure mem9 for OpenClaw. That is the main official entry point for the hosted mem9.ai service.

ClawHub can be used as an optional install source, but this guide assumes the official mem9.ai flow so the experience matches the website, dashboard, and support materials.

  • Install mem9 from the official onboarding flow.
  • Save the generated MEM9_API_KEY somewhere secure.
  • Use that key again whenever you reconnect on another machine.
  • After setup, open Your Memory to inspect what your agents are storing.

02

What mem9 Is

mem9 is long-term cloud memory for OpenClaw plus a visual dashboard for managing and analyzing that memory.

It turns fragile, scattered, hard-to-manage local memory into a durable product layer that is hosted, searchable, shareable, inspectable, and built for ongoing use.

03

Who This Guide Is For

This guide is for users who want the official hosted mem9.ai experience.

  • What mem9 is and why it is useful over the long term.
  • Why mem9 is often better than local memory files for durable workflows.
  • How to start from SKILL.md and what setup actually gives you.
  • What Your Memory does, which terms matter, and how reconnect or uninstall behaves.

What this guide does not cover

  • Self-hosting the Go backend.
  • Deploying the mem9 API service yourself.
  • Running your own database, infra, and operations stack.

04

Problems mem9 Solves

Default local memory approaches are tied to one machine, easy to lose after resets or migrations, hard to share across multiple agents, and difficult to review or manage over time.

mem9 makes important context survive across sessions, devices, and agents. It also makes memory visible through the dashboard so users can inspect, clean up, import, export, and analyze it instead of blindly trusting local files.

Just as importantly, mem9 aims to behave like a facts-and-insights memory layer rather than a pile of raw chat logs. The goal is to bring back the smallest useful set of relevant memory, not to keep stuffing old transcripts into prompts.

  • Less repetition of project background and user preferences.
  • Less loss after restarts, resets, or machine switches.
  • Less fragmentation when multiple agents need the same long-term knowledge.
  • More control over what the system actually remembers.

05

OpenClaw Native Memory vs mem9

The clearest difference is not that one is “good” and the other is “bad”. They solve different memory problems.

OpenClaw native memory is not useless. It is fundamentally about helping the agent write important information into local Markdown and then retrieve those files through indexing.

mem9 addresses a different class of need: memory that persists across sessions, resets, agents, devices, and ongoing operational workflows.

  • OpenClaw native memory is closer to a local knowledge notebook.
  • mem9 is closer to an external agent memory system.

When OpenClaw native memory is usually enough

  • A single OpenClaw agent.
  • A single machine.
  • You mainly rely on `MEMORY.md` and daily notes.
  • You are fine with recall returning original snippets or chunks.

When mem9 becomes the right product shape

  • Memory needs to survive across sessions, resets, and machines.
  • You do not want memory quality to depend on whether the agent wrote Markdown correctly.
  • You want long conversations to be distilled into more stable facts or insights.
  • You need multiple agents to share one memory pool.
  • You need different memory layers such as insight, pinned, and session.
  • You need APIs, a dashboard, analysis, and memory governance.

06

Core Capabilities

These are the product behaviors users will feel most directly.

Cloud long-term memory

Important context lives in the cloud instead of only inside the current chat session. That means resets, restarts, and device changes do not force your agent to start from zero.

Shared memory spaces

Multiple agents can connect to the same mem9 space and reuse the same long-term knowledge. This works well for multi-device usage, repeated automation, and shared project context.

appId sub-spaces under one API key

`appId` lets one MEM9_API_KEY hold several isolated memory sub-spaces for different applications, agents, environments, or product scenarios. A memory or raw session written with `appId: "docs"` is associated with that appId, while a write with omitted, null, empty, or whitespace `appId` belongs to the default/global appId.

When querying, omitting `appId` means global search across every appId under the API key. Passing a non-empty `appId` searches only that exact sub-space. Passing `appId=null` or `appId=` searches only the default/global appId. appId isolation does not change API key ownership, permissions, quota, or billing; it only scopes memory/session writes and read filters.

Hybrid recall

mem9 combines keyword and semantic recall so the system can search by exact terms and by current-task relevance. The goal is not perfect retrieval every time; the goal is to bring back better memory than a plain local file lookup can.

  • Smaller prompt payloads.
  • Less irrelevant context.
  • Lower token usage and lower cost.
  • Less pressure from context compaction in long-running sessions.

Your Memory dashboard

Your Memory is the official mem9 dashboard. It lets users view, manage, analyze, import, and export memories from a dedicated interface instead of treating memory as an invisible side effect.

Explicit “remember this” writes

Once mem9 is configured, a clear durable-write request such as “remember this” or “save this to mem9” should be treated as a real write request, not as casual conversation. The system can then decide which parts belong in long-term memory and confirm success or failure briefly.

Hook mode and Context Engine support

mem9 supports both Hook mode and Context Engine mode. Hook mode has the best compatibility today. Context Engine mode is the stronger path because it lets mem9 participate more directly in prompt assembly, message ingest, and compaction-related lifecycle behavior.

07

Official Install Flow

The simplest official install path is still the SKILL.md entry point. If users remember one thing, it should be that URL.

Start from mem9.ai/SKILL.md

Read https://mem9.ai/SKILL.md and follow the onboarding instructions inside OpenClaw. That is the source of truth for the official hosted workflow.

Typical setup choices inside OpenClaw

  • Create new mem9: generate a new API key and start a fresh memory space.
  • Reconnect mem9: enter an existing API key and reconnect to the same memory space.
  • Agents using the same API key share the same memory space in real time.
  • The API key can be switched later if the user intentionally wants a different memory space.

08

What You Get After Setup

From that point on, the main user actions are straightforward: ask the agent to remember important background, share one memory space across multiple agents, and use Your Memory whenever inspection or cleanup is needed.

  • A cloud-backed long-term memory space connected to mem9.ai.
  • A MEM9_API_KEY that must be kept safe for reconnect and recovery.
  • An OpenClaw environment that can explicitly store durable memory.
  • A dashboard entry point for viewing, organizing, importing, exporting, and analyzing memory.

09

Your Memory Dashboard

Your Memory is the main visual application in the mem9 product.

  • View existing memories.
  • Review, clean up, and manage entries.
  • Analyze memory content and patterns.
  • Import historical data when the user explicitly wants it.
  • Export current memory when needed.
Open Your Memory

10

Space Chains

Space Chain lets one recall key search several mem9 spaces in a deliberate order.

Use Space Chain when one agent should search layered knowledge sources without merging all data into one space. A common pattern is personal memory first, then team knowledge, then company knowledge.

Each node in the chain points to a normal mem9 space. The chain key is a separate key: clients call the same memory recall API with the chain key, and mem9 decides which spaces to visit.

  • Keep different ownership boundaries while still offering one recall endpoint.
  • Put the most specific or most trusted space first.
  • Reuse existing spaces without copying their memories into a new store.
  • Rotate or disable Space Chain keys without changing the underlying space keys.

How recall works

By default, recall visits nodes from top to bottom. If an early node returns a high-confidence match, mem9 can stop there and avoid searching later, broader spaces.

When Force scanAll is enabled, mem9 searches every node and globally reranks the combined results. This is useful when you want the broadest answer or you are comparing knowledge across all spaces.

Creating and importing chains

  • Create Space Chain starts a new ordered chain and gives you a chain key.
  • Import key adds an existing chain key to the console so you can manage or test a chain you already created.
  • Add nodes from existing spaces, then save the node order before relying on recall behavior.
  • Use the Recall test area to compare normal ordered recall with Force scanAll.

What to watch for

  • A chain node must be a normal mem9 space, not another Space Chain.
  • A node without a usable space key cannot participate in runtime recall.
  • If an imported space was created with an incompatible backend schema, recall may ask you to refresh or recreate that space before it can be searched.

11

Webhooks

Webhooks let external systems react when mem9 creates, deletes, or routes memory.

Use Webhooks when you need mem9 activity to update another system without polling the memory API. A webhook endpoint subscribes to events for one Space or one Space Chain, and mem9 delivers signed JSON payloads to the URL you configure.

mem9 remains the source of truth for endpoint configuration, signing secrets, event records, delivery attempts, retry state, and delivery history. Console and other products proxy or aggregate that state; they do not store webhook secrets or delivery logs separately.

  • Subscribe to `memory.added`, `memory.deleted`, and `space_chain.fact_routed`.
  • Create Space webhooks with a normal Space API key.
  • Create Space Chain webhooks with the `chain_` management key for that chain.
  • Use deliveries to audit attempts, HTTP responses, retry timing, and terminal failures.

Event payloads

  • `memory.added` is emitted after direct writes, pinned writes, smart ingest ADD actions, and successful routed target writes.
  • `memory.deleted` is emitted after single-memory and batch delete operations succeed.
  • `space_chain.fact_routed` is emitted on the Space Chain scope after a routing policy writes a matched fact to a target Space.
  • Smart ingest UPDATE-only reconciliation does not emit `memory.added`.

Signing and delivery

  • Every delivery includes `X-Mem9-Event-Id`, `X-Mem9-Event-Type`, `X-Mem9-Timestamp`, and `X-Mem9-Signature`.
  • The signature format is `v1=<hex_hmac_sha256>` over `<timestamp>.<event_id>.<raw_body>`.
  • Verify the timestamp tolerance, recompute the HMAC with the current signing secret, and compare in constant time.
  • mem9 retries transient failures with backoff and keeps delivery history for inspection.

Managing endpoints

  • Create and rotate responses show `signing_secret` once. List, get, and update responses never include it.
  • Production endpoints must use HTTPS. Development local HTTP is allowed only for localhost-style addresses.
  • Rotate the signing secret when a receiver is compromised or the secret was stored incorrectly.
Open API reference Open Console guide

12

Daily Usage Expectations

The most immediate day-to-day change is that users stop repeating the same project background, preferences, and working agreements every session.

What mem9 is good at remembering

  • Preferences and working style.
  • Project background and stable context.
  • Rules, standards, and conventions worth reusing.
  • Verified conclusions and recurring facts.

What users should not expect immediately

  • Every line of chat automatically becomes high-quality long-term memory.
  • All old local history is automatically imported during setup.

13

Reconnect, New Machine, and API Key Care

Reconnect

Reconnect means taking an existing MEM9_API_KEY and attaching the agent back to the original memory space. It does not create a new memory space.

Recovering on a new machine

  • Install the mem9 plugin again.
  • Write the same MEM9_API_KEY back into the config.
  • Keep the original official service URL unless you intentionally changed it.
  • Restart and verify that the original memory space is visible again.

Protecting the key

The API key should be treated like a real secret and stored in a password manager or another secure vault. It is the key to reconnecting the same memory space later.

14

Uninstall Behavior

Uninstalling mem9 affects the local machine setup, not the remote cloud data.

If the user wants the same memory back later, the usual path is simply to reinstall mem9 and reconnect with the original API key.

The uninstall flow is designed around a single restart, and resetting the current session is a separate follow-up after uninstall verification succeeds.

What uninstall does

  • Removes the local mem9 plugin configuration from that machine.
  • Restores the previous local memory configuration when applicable.
  • Cleans up local install residue.

What uninstall does not do

  • It does not delete remote mem9 cloud data.
  • It does not revoke the MEM9_API_KEY.
  • It does not automatically reset the current chat session.

15

Security and Trust

mem9 positions itself as a production-ready memory layer, not an opaque black box. The product story emphasizes clear data handling boundaries and production-grade cloud infrastructure.

  • Encryption in transit.
  • Encryption at rest.
  • Access controls.
  • Auditability.
  • Clear data processing boundaries.
  • Production-grade cloud infrastructure.
Security Overview TiDB Cloud Security White Paper

16

Product Expectations and Limits

mem9 is a long-term memory layer, not a universal reasoning engine

  • It is good at preserving important information over time.
  • It is good at bringing back relevant memory when needed.
  • It reduces repeated explanation and setup cost.
  • It does not guarantee perfect retrieval on every turn.

Setup is not the same thing as import

Initial setup is about connecting mem9, not uploading every historical local memory automatically. If the user wants local memory imported, that should happen as an explicit request, not as silent background collection.