🧠 Supermemory

Local graph-based memory plugin for OpenClaw with entity extraction, user profiles, and automatic forgetting — inspired by Supermemory

openclaw plugins install clawhub:openclaw-memory-supermemory

{
  "builtWithOpenClawVersion": "2026.3.26",
  "pluginApiRange": ">=2026.3.26"
}

{
  "bundledSkills": [],
  "capabilityTags": [
    "executes-code",
    "kind:memory"
  ],
  "channels": [],
  "commandNames": [],
  "configSchema": true,
  "configUiHints": false,
  "executesCode": true,
  "hooks": [],
  "httpRouteCount": 0,
  "materializesDependencies": false,
  "pluginKind": "memory",
  "providers": [],
  "runtimeId": "openclaw-memory-supermemory",
  "serviceNames": [],
  "setupEntry": false,
  "toolNames": []
}

{
  "hasProvenance": false,
  "scanStatus": "clean",
  "scope": "artifact-only",
  "sourceCommit": "https://github.com/ivanvmoreno/supermemory-openclaw/commit/c71f33c7ad8653a07167033c8d964895879996d8",
  "sourceRepo": "ivanvmoreno/supermemory-openclaw",
  "sourceTag": "https://github.com/ivanvmoreno/supermemory-openclaw/releases/tag/v0.3.1",
  "summary": "Validated package structure and linked the release to source metadata.",
  "tier": "source-linked"
}

{
  "latest": "0.3.1"
}

🧠 Supermemory OpenClaw Plugin

Local graph-based memory plugin for OpenClaw — inspired by Supermemory. Runs entirely on your machine with no cloud dependencies.

Disclaimer: This is an independent project. It is not affiliated with, endorsed by, or maintained by the Supermemory team. The name reflects architectural inspiration, not a partnership.

Features

• LLM Fact Extraction — Extracts discrete, entity-centric facts from each conversation turn via an LLM subagent, matching Supermemory's cloud approach locally.
• Graph Memory — Automatic entity extraction, relationship tracking (Updates / Extends / Derives), memory versioning with parent_memory_id chains.
• User Profiles — Static long-term facts + dynamic recent context, automatically maintained and injected into system prompt. Static memories (is_static) are protected from decay.
• Automatic Forgetting — Temporal expiration for time-bound facts (including absolute dates like "January 15"), decay for low-importance unused memories, contradiction resolution.
• Hybrid Search — BM25 keyword (FTS5) + graph-augmented multi-hop retrieval with MMR diversity re-ranking. Superseded memories are filtered at the query level. Vector similarity (sqlite-vec) used when available.
• Auto-Recall — Injects relevant memories + user profile before every AI turn via the before_prompt_build hook.
• OpenClaw Runtime Integration — Registers memory tools, a built-in memory search manager, and a pre-compaction memory flush plan when the host API supports them.

How It Works

flowchart LR
    subgraph input ["💬 Conversation"]
        A[User message] --> B[AI response]
    end

    subgraph extract ["🧠 Memory Engine"]
        C[Extract discrete facts via LLM]
        C --> D[Deduplicate]
        D --> E[Classify & embed]
    end

    subgraph graph ["🔗 Knowledge Graph"]
        F["Link entities\n(people, projects)"]
        F --> G{Relationship detection}
        G --> H["🔄 Updates — new fact\nsupersedes old"]
        G --> I["➕ Extends — enriches\nexisting fact"]
        G --> J["🔮 Derives — inferred\nconnection"]
    end

    subgraph recall ["🔎 Recall"]
        K["User Profile\n(static + dynamic facts)"]
        L["Hybrid Search\n(vector + keyword + graph)"]
        K --> M[Inject into next AI turn]
        L --> M
    end

    B --> C
    E --> F
    J --> K
    H --> K
    I --> K

1. You talk to your AI normally. Share preferences, mention projects, discuss problems.
2. Auto-capture uses your configured LLM to extract discrete facts from the last conversation turn (both user and assistant messages).
3. Graph engine links each extracted fact to entities and detects relationships:
   • Updates — "Iván moved to Copenhagen" supersedes "Iván lives in Madrid"
   • Extends — "Iván leads a research team of 4" enriches "Iván is an AI Scientist at Santander"
   • Derives — Inferred connections from shared entities
4. Auto-recall injects your user profile + relevant memories before each AI turn.
5. Automatic forgetting cleans up expired time-bound facts and decays unused low-importance memories.

Quick Start

Step 1: Install the plugin

openclaw plugins install openclaw-memory-supermemory

Step 2: Configure OpenClaw

Edit ~/.openclaw/openclaw.json and add both the memory slot and the plugin entry:

{
  plugins: {
    // REQUIRED: Assign this plugin to the memory slot
    slots: {
      memory: "openclaw-memory-supermemory"
    },
    // RECOMMENDED: Suppress the auto-load security warning
    allow: ["openclaw-memory-supermemory"],
    // Plugin configuration
    entries: {
      "openclaw-memory-supermemory": {
        enabled: true,
        config: {
          embedding: {
            provider: "openai",
            model: "text-embedding-3-small",
            apiKey: "${OPENAI_API_KEY}"    // reads from env var
          },
          autoRecall: true,
          autoCapture: true
        }
      }
    }
  }
}

Important: The slots.memory line is required — without it, OpenClaw won't use the plugin even if it's installed.

Step 3: Restart OpenClaw

Restart the OpenClaw gateway for the plugin to load.

Step 4: Verify it works

openclaw supermemory stats

You should see output like:

Total memories:      0
Active memories:     0
Superseded memories: 0
Entities:            0
Relationships:       0
Vector search:       unavailable

Zero counts are normal on first run. Vector search: unavailable is expected — see Vector Search below.

Embedding Providers

You need an embedding provider for semantic search. Choose one:

OpenAI (recommended for simplicity)

embedding: {
  provider: "openai",
  model: "text-embedding-3-small",
  apiKey: "${OPENAI_API_KEY}"
}

Set the environment variable before starting OpenClaw:

export OPENAI_API_KEY="sk-..."

Ollama (fully local, no API key)

Install Ollama and pull a model:

ollama pull nomic-embed-text

embedding: {
  provider: "ollama",
  model: "nomic-embed-text"
}

Other OpenAI-compatible providers

Any provider with an OpenAI-compatible /v1/embeddings endpoint works:

embedding: {
  provider: "openai",
  model: "your-model-name",
  apiKey: "${YOUR_API_KEY}",
  baseUrl: "https://your-provider.com/v1"
}

Supported models (auto-detected dimensions)

For other models, set embedding.dimensions explicitly.

AI Tools

The AI uses these tools autonomously:

CLI Commands

openclaw supermemory stats              # Show memory statistics
openclaw supermemory search <query>     # Search memories
openclaw supermemory search "rust" --limit 5
openclaw supermemory profile            # View user profile
openclaw supermemory profile --rebuild  # Force rebuild profile
openclaw supermemory wipe --confirm     # Delete all memories

Verifying Memories

After chatting with the AI, you can verify memories are being captured:

# Check memory counts increased
openclaw supermemory stats

# Search for something you mentioned
openclaw supermemory search "your topic"

# View your auto-built profile
openclaw supermemory profile

Vector Search

The plugin uses FTS5 keyword search + graph traversal by default. Vector similarity search requires sqlite-vec, which is bundled with OpenClaw's built-in memory system but not automatically available to external plugins.

If your OpenClaw build includes sqlite-vec, the plugin will detect and use it automatically.

Troubleshooting

"plugins.allow is empty" warning

Suppress it by adding:

plugins: {
  allow: ["openclaw-memory-supermemory"]
}

Configuration Reference

Fact Extraction

By default, the plugin uses your configured LLM to extract discrete, entity-centric facts from each conversation turn.

Input conversation:

"Caught up with Iván today. He's working at Santander as an AI Scientist now, doing research on knowledge graphs. He lives in Madrid and mentioned a deadline next Tuesday for a paper submission."

Extracted memories:

• Iván works at Santander as an AI Scientist
• Iván researches knowledge graphs
• Iván lives in Madrid
• Iván has a paper submission deadline next Tuesday

Each fact is stored as a separate memory with automatic entity linking, relationship detection (Updates/Extends/Derives), and temporal expiration.

Set captureMode: "off" to disable auto-capture entirely.

Architecture

openclaw-memory-supermemory/
├── index.ts                    # Plugin entry
├── openclaw.plugin.json        # Plugin manifest (kind: "memory")
├── tests/
│   └── integration/
│       └── longmemeval/
│           ├── fixtures/       # Bundled LongMemEval test artifacts
│           ├── README.md       # Test layout and artifact notes
│           └── run.ts          # Local OpenClaw integration battery / benchmark runner
├── src/
│   ├── config.ts               # Config parsing + defaults
│   ├── db.ts                   # SQLite: memories, entities, relationships, profiles
│   ├── embeddings.ts           # Ollama + OpenAI-compatible embedding providers
│   ├── fact-extractor.ts        # LLM fact extraction via OpenClaw subagent
│   ├── graph-engine.ts         # Entity extraction, relationship detection, temporal parsing
│   ├── memory-text.ts          # Injected/synthetic memory filtering and prompt-safe sanitization
│   ├── search.ts               # Hybrid search (vector + FTS5 + graph)
│   ├── profile-builder.ts      # Static + dynamic user profile
│   ├── forgetting.ts           # Temporal decay, expiration, cleanup
│   ├── tools.ts                # Agent tools (search, store, forget, profile)
│   ├── hooks.ts                # Auto-recall + guarded auto-capture hooks
│   └── cli.ts                  # CLI commands

Storage

All data stored in a single SQLite database:

• memories — Text, embeddings, importance, category, expiration, access tracking, is_static, parent_memory_id
• entities — Extracted entities (people, projects, tech, emails, URLs)
• entity_mentions — Links between memories and entities
• relationships — Graph edges (updates / extends / derives)
• profile_cache — Cached static + dynamic user profile
• memories_fts — FTS5 virtual table for keyword search
• memories_vec — sqlite-vec virtual table for vector similarity (when available)

LongMemEval Integration

The repo includes a LongMemEval runner that evaluates this plugin through a real local OpenClaw agent invocation while keeping benchmark state isolated from your normal ~/.openclaw profile.

# One example per main LongMemEval category + one abstention case
bun run test:integration:longmemeval

# Run the whole bundled oracle fixture
bun run test:integration:longmemeval --preset full

# Run the official LongMemEval evaluator afterwards
bun run test:integration:longmemeval --run-official-eval --official-repo /tmp/LongMemEval

The runner auto-loads repo-root .env.local and .env before reading env defaults. Start from .env.sample. The only supported runner env defaults are LONGMEMEVAL_SOURCE_STATE_DIR and LONGMEMEVAL_OFFICIAL_REPO.

What the runner does:

1. Uses the bundled oracle fixture by default, or a file passed via --data-file
2. Creates an isolated ~/.openclaw-<profile> profile
3. Copies auth and model metadata from LONGMEMEVAL_SOURCE_STATE_DIR (default: ~/.openclaw)
4. Imports each benchmark instance into a fresh plugin DB
5. Asks the benchmark question through openclaw agent --local
6. Writes a predictions.jsonl file plus a run summary JSON