🧠 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.

How It Works

• Auto-capture — After each AI response, an LLM subagent extracts typed atomic memories (facts, episodes, preferences) and raw entity mentions from the turn, deduplicates them lexically and by vector similarity, then stores them in a local SQLite knowledge graph.
• Graph storage — Memories are linked to canonical entities and connected by relationship edges: updates (newer fact supersedes older) and related (connected facts sharing entities).
• Background maintenance — A periodic job merges entity aliases (e.g. "Ivan" / "Iván"), expires stale episodic memories, and backfills any missing embeddings.
• Auto-recall — Before each AI turn, hybrid search (BM25 + vector + graph hops) retrieves the most relevant memories and your user profile, which are injected into the prompt context.

Sequence diagrams available in docs/diagrams/.

Quick Start

Step 1: Install the plugin

openclaw plugins install openclaw-memory-supermemory

Step 2: Run the setup wizard

openclaw supermemory configure

Step 3: Restart OpenClaw

Restart the OpenClaw gateway for the plugin to load.

openclaw gateway restart

Step 4: Check the saved configuration

openclaw supermemory status

You should see a summary of the plugin state, embedding provider, model, and database path.

Step 5: Verify it works

openclaw supermemory stats

You should see output like:

Total memories:      0
Active memories:     0
Superseded memories: 0
Entities:            0
Relationships:       0

Zero counts are normal on first run.

Upgrade Note

If startup fails after upgrading, reinstalling, or switching between older builds, wipe the memory database and let the plugin recreate it:

openclaw supermemory wipe --confirm

Embedding Providers

Supported providers and auto-detected dimensions:

Model	Provider	Dimensions
embeddinggemma	Ollama	768
qwen3-embedding	Ollama	4096
bge-m3	Ollama	1024
all-minilm	Ollama	384
nomic-embed-text	Ollama	768
snowflake-arctic-embed2	Ollama	1024
mxbai-embed-large	Ollama	1024
snowflake-arctic-embed	Ollama	1024
text-embedding-3-small	OpenAI	1536
text-embedding-3-large	OpenAI	3072

Set provider to "ollama" or "openai". Any OpenAI-compatible endpoint also works via baseUrl.

For unlisted models, set embedding.dimensions explicitly. When you do, the plugin forwards that size to providers that support variable-width embeddings and rebuilds vector-state under the new dimension.

AI Tools

The AI uses these tools autonomously:

Tool	Description
memory_search	Search across memories using vector + keyword + graph retrieval when embeddings are enabled, otherwise keyword + graph (or keyword-only if graphWeight is 0)
memory_store	Save information with automatic entity extraction and relationship detection
memory_forget	Delete memories by ID or search query
memory_profile	View/rebuild the automatically maintained user profile

CLI Commands

openclaw supermemory configure          # Interactive setup wizard
openclaw supermemory status             # Show current configuration
openclaw supermemory stats              # Show memory statistics
openclaw supermemory search <query>     # Search memories
openclaw supermemory search "<term>" --limit 5
openclaw supermemory profile            # View user profile
openclaw supermemory profile --rebuild  # Force rebuild profile
openclaw supermemory wipe --confirm     # Wipe persisted memory data and re-initialize storage

Interactive Setup

Run openclaw supermemory configure for a guided wizard that reads your existing ~/.openclaw/openclaw.json and writes the plugin entry back after prompting for:

• Plugin enabled/disabled
• Auto-capture and auto-recall toggles
• Embedding provider, model, API key, and base URL
• Custom database path

Run openclaw supermemory status at any time to print a summary of the current configuration.

Run openclaw supermemory wipe --confirm to wipe the SQLite memory store and re-initialize an empty database without changing your saved plugin configuration.

Slash Commands

Three slash commands are registered for quick in-chat memory access:

Command	Description
/remember <text>	Store a memory immediately, bypassing auto-capture
/recall <query>	Run a hybrid search and display matching memories
/forget <description>	Delete a memory by description; auto-deletes on high-confidence single match, otherwise lists candidates

Vector Search

The plugin always uses FTS5 keyword search. When graphWeight > 0, it also augments results with graph traversal. When embeddings are enabled, it additionally uses sqlite-vec for vector similarity search and vector-based deduplication.

Because sqlite-vec is bundled with OpenClaw's built-in memory system, the plugin automatically detects and loads the extension from the host environment when embeddings are enabled. This means vector similarity search is usually available out-of-the-box without requiring any additional installation or configuration.

If you prefer to avoid embedding work entirely, set embedding.enabled: false in your configuration. That disables embedding generation, vector retrieval, and vector-based deduplication while preserving any existing stored vectors on disk.

When you turn embeddings back on later, the plugin starts a background backfill. It reindexes any stored vectors first, then embeds older active memories that were captured while embeddings were disabled. Startup is not blocked while this runs.

If you change the embedding provider, model, or explicit dimensions, the plugin clears only its stored vector-state and then backfills under the new embedding space. Memory texts, entities, and relationships stay intact.

Configuration Reference

All settings are optional. The plugin now exposes only the operational knobs that still affect behavior directly.

Core

Option	Type	Default	Description
embedding.enabled	boolean	true	Enable or disable embedding generation, vector retrieval, and vector deduplication
embedding.provider	string	"ollama"	Embedding provider (ollama, openai, etc.)
embedding.model	string	"embeddinggemma"	Embedding model name
embedding.apiKey	string	—	API key (cloud providers only, supports ${ENV_VAR} syntax)
embedding.baseUrl	string	—	Custom API base URL
embedding.dimensions	number	auto	Override vector dimensions and request that size from providers that support it
autoCapture	boolean	true	Auto-capture memories from conversations
autoRecall	boolean	true	Auto-inject memories + profile into context
dbPath	string	~/.openclaw/memory/supermemory.db	SQLite database path
debug	boolean	false	Enable verbose logging

Profile And Prompt

Option	Type	Default	Description
profileFrequency	number	50	Rebuild the profile every N interactions
maxLongTermItems	number	20	Max memories included in the long-term profile section
maxRecentItems	number	10	Max memories included in the recent profile section
recentWindowDays	number	7	How many days count as recent for episodic memories
profileScanLimit	number	1000	Max active memories scanned when rebuilding the profile
promptMemoryMaxChars	number	500	Max characters per memory item when injecting profile or recall context

Recall And Search

Option	Type	Default	Description
maxRecallResults	number	10	Max results returned by the memory_search tool. Auto-recall uses a separate cap.
vectorWeight	number	0.5	Weight for vector similarity in hybrid search
textWeight	number	0.3	Weight for BM25 keyword search
graphWeight	number	0.2	Weight for graph-augmented retrieval
minScore	number	0.1	Minimum combined score for a result to be returned
vectorMinScoreFactor	number	0.5	Multiplied by minScore to set the vector search cut-off (effective floor: minScore × vectorMinScoreFactor)
graphSeedLimit	number	5	Number of top-scored results used to seed the graph hop walk
graphHopDepth	number	2	Depth of graph traversal per seed node
mmrLambda	number	0.7	MMR trade-off between relevance (1.0) and diversity (0.0) in result re-ranking
autoRecallMaxMemories	number	5	Hard cap on memories injected into the prompt during auto-recall (independent of maxRecallResults)
autoRecallMinScore	number	0.3	Minimum score for a memory to be injected during auto-recall

Capture And Extraction

Option	Type	Default	Description
captureMaxChars	number	2000	Max characters from the assembled conversation turn sent to auto-capture extraction
extractorMaxItems	number	10	Max memories the LLM extractor may return per conversation turn

Relationships And Forgetting

Option	Type	Default	Description
forgetExpiredIntervalMinutes	number	60	Minutes between forgetting cleanup runs
temporalDecayDays	number	90	Days before stale unpinned episodic memories decay
nearDuplicateThreshold	number	0.95	Vector cosine similarity above which an incoming memory is treated as a near-duplicate and skipped
lexicalDuplicateThreshold	number	0.88	Lexical overlap score above which an incoming memory is treated as a lexical duplicate and skipped
updateVectorMinScore	number	0.55	Minimum vector similarity for a candidate memory to be considered for an updates relationship
maxRelatedEdges	number	5	Maximum number of related graph edges written per memory on ingestion

Semantic Extraction

The plugin uses your configured LLM to extract typed atomic memories, raw entity mentions, and temporal metadata 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:

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

Each extracted memory is stored separately with:

• a memoryType (fact, preference, or episode)
• raw entity mentions such as Iván, Santander, and Madrid
• optional temporal metadata such as expiresAtIso

Those raw mentions are linked to canonical entities later, so the system can preserve original surface forms while still grouping aliases over time.

Set autoCapture: false to disable auto-capture entirely.

Architecture

For an in-depth breakdown of the graph logic, scoring algorithms, and background processes, see the following document.

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, canonical entities, aliases, relationships, profiles
│   ├── embeddings.ts           # Ollama + OpenAI-compatible embedding providers
│   ├── fact-extractor.ts       # LLM semantic extraction + relationship/entity resolvers
│   ├── graph-engine.ts         # Storage orchestration, alias linking, update resolution
│   ├── entity-text.ts          # Entity alias normalization helpers
│   ├── semantic-runtime.ts     # Shared subagent runtime helpers for JSON tasks
│   ├── memory-text.ts          # Injected/synthetic memory filtering and prompt-safe sanitization
│   ├── search.ts               # Hybrid search (vector + FTS5 + graph)
│   ├── profile-builder.ts      # Long-term + recent user profile
│   ├── forgetting.ts           # Expiration, stale-episode cleanup, deferred entity merging
│   ├── tools.ts                # Agent tools (search, store, forget, profile)
│   ├── hooks.ts                # Auto-recall + guarded auto-capture hooks
│   ├── cli.ts                  # CLI commands + slash command registration
│   ├── configure.ts            # Interactive setup wizard + status command
│   └── logger.ts               # Named, debug-aware plugin logger

Storage

All data stored in a single SQLite database:

• memories — Text, embeddings, memory type, expiration, access tracking, pinned, parent_memory_id
• entities — Canonical entity clusters
• entity_aliases — Raw observed entity names / surface forms
• entity_mentions — Links between memories and aliases
• relationships — Graph edges (updates / related)
• profile_cache — Cached long-term + recent user profile
• memories_fts — FTS5 virtual table for keyword search
• memories_vec — sqlite-vec virtual table for vector similarity (if enabled)

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.

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