MindClaw

Structured long-term memory for AI agents with fact curation, conflict detection, importance scoring, timeline reconstruction, and OpenClaw integration.

Security Scan

MindClaw mostly aligns with a memory/knowledge-graph tool, but there are several inconsistencies and behavior (automatic registration, writing other tools' config, repo/manifest mismatches, credential-capture rules) that merit review before installing.

Purpose & Capability

The name/description (structured long-term memory for agents, OpenClaw integration) match the code and CLI features (SQLite store, BM25 search, Ollama semantic support, sync to OpenClaw MEMORY.md). However there are small metadata inconsistencies (registry lists no homepage/source while SKILL.md and other files reference different GitHub repos: Blue8x/MindClaw vs Blue8x/Clawtion), which reduces confidence in provenance.

Instruction Scope

Runtime instructions and code explicitly read/write user files: ~/.mindclaw/config.json, a DB under ~/.mindclaw, and OpenClaw workspace files (~/.openclaw/workspace/MEMORY.md). The tool also auto-registers itself with other runtimes (Claude Desktop and OpenClaw) by modifying their config files. The capture rules will scan conversation text for credential-like patterns and attempt to redact them, but the capability to detect/store redacted credential context is present — this increases the risk of sensitive data being processed and persisted unintentionally.

Install Mechanism

No install spec bundled in the registry; SKILL.md instructs using pip install mindclaw[mcp], which is a normal delivery mechanism. The bundle includes full source/pyproject making local inspection possible. No network downloads from obscure URLs are required by the instructions. The mismatch in repository names/URLs (Clawtion vs MindClaw) is a provenance anomaly to check before pip installing from an external registry.

Credentials

The skill does not require secrets or external credentials to function, and declares no required env vars, but supports MINDCLAW_DB / MINDCLAW_AGENT / MINDCLAW_OPENCLAW_WORKSPACE overrides and may auto-detect a local Ollama instance. The capture engine looks for credential-like text in conversation streams (and redacts values) — that behavior is plausible for a memory tool but is sensitive and should be considered when granting agents access to conversation logs. The tool also edits other apps' config files (Claude Desktop, OpenClaw) to register itself — those actions need explicit user consent.

Persistence & Privilege

The skill persists long-term data (~/.mindclaw/config.json, SQLite DB) which is expected. However it also offers automated registration that updates other tools' configuration (Claude Desktop and OpenClaw tools registries). Modifying other tools' configs is out-of-scope for a simple memory store and increases privilege/persistence surface; verify exactly what files are changed and that you consent to those changes.

Scan Findings in Context

[pre-scan] unexpected: No static regex-based pre-scan findings were reported. That does not imply safety — the package contains code that writes config files and edits other tool registries, which are behavioral risks rather than pattern-matched signatures.

What to consider before installing

Before installing or enabling MindClaw, consider the following: 1) Verify provenance: confirm the pip package and GitHub repository are the official project (metadata in files references multiple repo names — resolve that mismatch). 2) Backup OpenClaw/agent files (MEMORY.md, ~/.openclaw/tools.json, Claude Desktop config) because MindClaw's setup/mcp install will modify those files. 3) Audit the mcp install/setup code paths (mcp_server.py and CLI install handlers) to see precisely what files they modify and whether they call external endpoints. 4) If you accept automatic registration, run setup interactively rather than allowing an agent to call setup_mindclaw without human approval. 5) Be cautious about feeding conversation logs to auto-capture: the capture rules detect credential-like strings (they attempt to redact values but still store context) — do not pass secrets into capture or disable auto-capture for sensitive streams. 6) Prefer testing in a sandbox / VM or with a non-production OpenClaw workspace and a disposable agent namespace until you are satisfied with behavior.

Persistent memory and knowledge graph for AI agents. Remember everything, forget nothing.

MindClaw is a structured long-term knowledge layer for OpenClaw agents. Where OpenClaw stores raw conversational memory in Markdown files, MindClaw stores curated facts, decisions, and relationships with full metadata — conflict detection, confirmation reinforcement, importance scoring, and a knowledge graph.

Memories sync back to OpenClaw's MEMORY.md so they are also searchable via OpenClaw's native memory_search tool.

Install

pip install mindclaw[mcp] && mindclaw setup

The setup wizard configures your workspace path, agent name, and registers MindClaw with Claude Desktop and/or OpenClaw in one step.

What agents can do

MCP Tool	Purpose
setup_mindclaw	One-call setup: configure, register with OpenClaw, initial sync
remember	Store a fact, decision, preference, or error with metadata
recall	BM25 + semantic hybrid search with temporal decay and MMR diversity
context_block	Token-limited memory block ready to inject into any LLM prompt
capture	Auto-extract structured memories from conversation text
confirm	Reinforce a memory that proved correct (boosts importance)
forget	Archive or hard-delete a memory
pin_memory	Mark a memory as permanent — immune to decay
timeline	Reconstruct what happened in the last N hours
consolidate	Merge near-duplicate memories automatically
link	Connect two memories in the knowledge graph
stats	Check store health and memory breakdown
sync_openclaw	Export all memories to OpenClaw's MEMORY.md
import_markdown	Import from any OpenClaw MEMORY.md or daily log
unpin_memory	Remove a pin from a memory

OpenClaw integration

MindClaw mirrors OpenClaw's search pipeline exactly:

Feature	OpenClaw	MindClaw
BM25 keyword search	✓	✓
Semantic embeddings	local GGUF / OpenAI / Gemini	Ollama (auto-detect, zero deps)
Temporal decay	--temporalDecay	--decay + --halflife
MMR diversity	mmr.enabled	--mmr + --mmr-lambda
Per-agent isolation	per-agentId SQLite	--agent <name>

After mindclaw sync, all structured memories appear in MEMORY.md and are found by OpenClaw's native memory_search — no agent code changes needed.

Recommended agent loop

1. context_block(query)   → inject relevant context before answering
2. remember(content)      → store key facts and decisions after acting
3. capture(conversation)  → extract structured memories from session logs
4. confirm(id)            → reinforce memories that proved correct
5. sync_openclaw()        → push to OpenClaw's MEMORY.md (cross-tool visibility)
6. consolidate()          → periodic dedup maintenance

Configuration

Run once, never repeat flags:

mindclaw setup

Saves ~/.mindclaw/config.json with your workspace path, agent name, and DB path. Priority chain: CLI flag > MINDCLAW_* env var > config file > built-in default

Requirements

• Python 3.10+
• Zero mandatory dependencies (core uses only stdlib)
• Optional: pip install mindclaw[mcp] for MCP server
• Optional: Ollama running locally for semantic search (auto-detected)

Source

GitHub: https://github.com/Blue8x/MindClaw