🦞 MemOS Local — OpenClaw Memory Plugin

Persistent local conversation memory for OpenClaw AI Agents. Every conversation is automatically captured, semantically indexed, and instantly recallable.

Full-write | Hybrid Search (FTS5 + Vector) | RRF Fusion | MMR Diversity | Recency Decay

Features

• Auto-capture — Stores user, assistant, and tool messages after each agent turn
• Semantic chunking — Preserves complete code blocks, function bodies, and paragraph boundaries
• Hybrid retrieval — FTS5 keyword + vector semantic dual-channel search with RRF fusion
• LLM summarization — One-sentence summary per chunk for fast browsing
• Multi-provider — OpenAI, Anthropic, Gemini, Cohere, Voyage, Mistral, Bedrock, or local offline
• Web viewer — Built-in dashboard at http://127.0.0.1:18799 with CRUD, search, filters, pagination
• Privacy first — All data in local SQLite, no cloud uploads, password-protected viewer

Quick Start

1. Install

From npm (recommended):

openclaw plugins install @memtensor/memos-local-openclaw-plugin

The plugin is installed under ~/.openclaw/extensions/ and registered as memos-local. No clone or build required.

Important: Installing the plugin does not start the Memory Viewer. The viewer HTTP service is started only when the OpenClaw gateway is running. After install, you must configure openclaw.json (step 2) and start or restart the gateway (step 3); then the viewer will be available at http://127.0.0.1:18799.

From source (development):

git clone https://github.com/MemTensor/MemOS.git
cd MemOS/apps/memos-local-openclaw
npm install && npm run build
openclaw plugins install .

2. Configure

Add the plugin config to ~/.openclaw/openclaw.json:

{
  "plugins": {
    "slots": {
      "memory": "memos-local"
    },
    "entries": {
      "memos-local": {
        "enabled": true,
        "config": {
          "embedding": {
            "provider": "openai_compatible",
            "endpoint": "https://your-embedding-api.com/v1",
            "apiKey": "your-embedding-key",
            "model": "bge-m3"
          },
          "summarizer": {
            "provider": "openai_compatible",
            "endpoint": "https://api.openai.com/v1",
            "apiKey": "sk-xxx",
            "model": "gpt-4o-mini",
            "temperature": 0
          }
        }
      }
    }
  }
}

Embedding Provider Options

| Provider | provider value | Example model | Notes | |---|---|---|---| | OpenAI / compatible | openai_compatible | bge-m3, text-embedding-3-small | Any OpenAI-compatible API | | Gemini | gemini | text-embedding-004 | Requires apiKey | | Cohere | cohere | embed-english-v3.0 | Separates document/query embedding | | Voyage | voyage | voyage-2 | | | Mistral | mistral | mistral-embed | | | Local (offline) | local | — | Uses Xenova/all-MiniLM-L6-v2, no API needed |

No embedding config? The plugin falls back to the local model automatically. You can start with zero configuration and add a cloud provider later for better quality.

Summarizer Provider Options

| Provider | provider value | Example model | |---|---|---| | OpenAI / compatible | openai_compatible | gpt-4o-mini | | Anthropic | anthropic | claude-3-haiku-20240307 | | Gemini | gemini | gemini-1.5-flash | | AWS Bedrock | bedrock | anthropic.claude-3-haiku-20240307-v1:0 |

No summarizer config? A rule-based fallback generates summaries from the first sentence + key entities. Good enough to start.

Environment Variable Support

Use ${ENV_VAR} placeholders in config to avoid hardcoding keys:

{
  "apiKey": "${OPENAI_API_KEY}"
}

3. Start or Restart the Gateway

The Memory Viewer and all plugin features only run when the OpenClaw gateway is running. After installing and configuring the plugin, start (or restart) the gateway:

openclaw gateway stop    # if already running
openclaw gateway install # ensure LaunchAgent is installed (macOS)
openclaw gateway start

Once the gateway is up, the plugin loads and starts the Memory Viewer at http://127.0.0.1:18799.

4. Verify Installation

# Check the gateway log
tail -20 ~/.openclaw/logs/gateway.log

You should see:

memos-local: initialized (db: ~/.openclaw/memos-local/memos.db)
memos-local: started (embedding: openai_compatible)
╔══════════════════════════════════════════╗
║  MemOS Memory Viewer                     ║
║  → http://127.0.0.1:18799               ║
║  Open in browser to manage memories       ║
╚══════════════════════════════════════════╝

5. Verify Memory is Working

Step A — Have a conversation with your OpenClaw agent about anything.

Step B — Open the Memory Viewer at http://127.0.0.1:18799 and check that the conversation appears.

Step C — In a new conversation, ask the agent to recall what you discussed:

You: Do you remember what we talked about?
Agent: (calls memory_search) Yes, we discussed...

Step D — Check the gateway log for ingest activity:

grep -E "Stored chunk|Chunked turn|Dedup" ~/.openclaw/logs/gateway.log | tail -10

You should see lines like:

Chunked turn=1772459198930-839rr3 into 3 chunks
Stored chunk=667f289e kind=paragraph len=392 hasVec=true
Stored chunk=107d7f32 kind=tool_result role=tool len=210 hasVec=true

6. Run the Smoke Test (Optional)

If you have the source (e.g. cloned the repo or develop locally):

cd MemOS/apps/memos-local-openclaw   # or the path where the plugin source is
cp .env.example .env
# Edit .env with your actual API keys
npx tsx scripts/smoke-test.ts

The smoke test writes test conversations, searches for them, verifies timeline and get operations, and checks anti-writeback protection. If you installed only from npm, you can skip this step.

Reinstall (when install fails or you need to upgrade)

If you see "plugin already exists" or "plugin not found" after deleting the plugin folder:

1. Option A — Use OpenClaw install (recommended when config does not reference the plugin yet)
   Delete the extension folder, then run:

   rm -rf ~/.openclaw/extensions/memos-local
   openclaw plugins install @memtensor/memos-local-openclaw-plugin

   If your openclaw.json already has plugins.slots.memory: "memos-local" and plugins.entries.memos-local, the config check may fail with "plugin not found" before install runs. In that case use Option B.

2. Option B — Manual install (when config already references memos-local)
   Delete the folder, then install from npm and extract:

   rm -rf ~/.openclaw/extensions/memos-local
   cd /tmp
   npm pack @memtensor/memos-local-openclaw-plugin
   tar -xzf memtensor-memos-local-openclaw-plugin-*.tgz
   mv package ~/.openclaw/extensions/memos-local

   No need to run npm install — on first load the plugin will install dependencies automatically. Then restart the gateway: openclaw gateway stop then openclaw gateway start.

Plugin shows as "error" in openclaw plugins list? (e.g. Cannot find module '@sinclair/typebox')
If auto-install failed (e.g. npm not in PATH when the gateway runs), install dependencies manually once:

cd ~/.openclaw/extensions/memos-local && npm install --omit=dev

Then restart the gateway.

Agent Tools

The plugin registers 4 tools that your agent can use:

| Tool | Purpose | |---|---| | memory_search | Search memories by natural language query | | memory_timeline | Get surrounding context for a search hit | | memory_get | Get full original text of a memory chunk | | memory_viewer | Get the URL of the web dashboard |

The agent uses these automatically via the SKILL.md prompt guide.

Memory Viewer

Open http://127.0.0.1:18799 in your browser:

Viewer won't open or page not loading?

• The viewer is started by the plugin when the gateway starts. It does not run at install time.

• Ensure the gateway is running: openclaw gateway start (or restart with openclaw gateway stop then openclaw gateway start).

• Ensure the plugin is enabled in ~/.openclaw/openclaw.json: plugins.slots.memory = "memos-local" and plugins.entries.memos-local.enabled = true.

• Check the gateway log: tail -30 ~/.openclaw/logs/gateway.log — you should see MemOS Memory Viewer and → http://127.0.0.1:18799. If the viewer fails to bind (e.g. port in use), the log will show a warning.

• First visit: set a password (min 4 chars)

• Browse, search, create, edit, delete memories

• Filter by role (user/assistant/tool), type, time range (down to seconds)

• Pagination (30 per page)

Forgot password? Click "Forgot password?" on the login page and use the reset token from the gateway log:

# 必须用 "password reset token:" 才能匹配到带 token 的那一行（不要用 "reset token"）
grep "password reset token:" /tmp/openclaw/openclaw-*.log ~/.openclaw/logs/gateway.log 2>/dev/null | tail -1

输出可能是纯文本一行，或一段 JSON；从中复制 password reset token: 后面的 32 位 hex 即可。

Advanced Configuration

All optional — shown with defaults:

{
  "config": {
    "recall": {
      "maxResultsDefault": 6,     // Default search results
      "maxResultsMax": 20,        // Max search results
      "minScoreDefault": 0.45,    // Default min score threshold
      "minScoreFloor": 0.35,      // Lowest allowed min score
      "rrfK": 60,                 // RRF fusion constant
      "mmrLambda": 0.7,           // MMR relevance vs diversity (0-1)
      "recencyHalfLifeDays": 14   // Time decay half-life
    },
    "dedup": {
      "similarityThreshold": 0.93 // Cosine similarity for dedup
    },
    "viewerPort": 18799           // Memory Viewer port
  }
}

How It Works

Write path (automatic on every agent turn):

Conversation → Capture (filter roles) → Semantic Chunk → LLM Summarize
→ Embed → Dedup Check → Store (SQLite + FTS5 + Vector)

Read path (when agent calls memory_search):

Query → FTS5 + Vector dual recall → RRF Fusion → MMR Rerank
→ Recency Decay → Score Filter → Top-K Results

See the full documentation in the repo (or open www/docs/index.html locally) for detailed architecture and algorithm explanations.

Data Location

Whether you install from npm or from source, the plugin stores data under your OpenClaw state directory:

| File | Path | |---|---| | Database | ~/.openclaw/memos-local/memos.db | | Viewer auth | ~/.openclaw/viewer-auth.json | | Gateway log | ~/.openclaw/logs/gateway.log | | Plugin code (npm install) | ~/.openclaw/extensions/ (managed by OpenClaw) |

License

MIT