Mindclaw

# MindClaw

> 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

```bash
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...

# MindClaw

[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![Version](https://img.shields.io/badge/version-0.3.1-green.svg)](#)
[![License](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-server-orange.svg)](#mcp-server-native-agent-integration)
[![ClawHub](https://img.shields.io/badge/clawhub.ai-ready-blueviolet.svg)](https://clawhub.ai)

> **Remember everything, forget nothing.**

Persistent memory and knowledge graph for AI agents.

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.

## Features

- Persistent memory store in SQLite (zero external dependencies for core)
- **MCP server** — expose all tools natively to Claude Desktop, OpenClaw, and any MCP runtime
- **OpenClaw Markdown bridge** — `sync` exports to `MEMORY.md`; `md-import` imports daily logs; in-place update preserves agent's own notes
- **BM25 full-text search** (zero deps, superior to TF-IDF) + **Ollama semantic embeddings** (auto-detected, no extra packages)
- **Temporal decay at recall** — `--decay` flag: recent memories rank higher (`score × e^(-λ × age)`, same as OpenClaw)
- **MMR diversity re-ranking** — `--mmr` flag: reduces near-duplicate results (same algorithm as OpenClaw)
- **Agent namespaces** — scope memories per agent with `--agent <name>`
- **Pinned memories** — mark critical facts as never-decayable
- **Conflict detection** — warns before storing contradictory information
- **Confirmation system** — reinforce memories to boost their importance score
- **Context window builder** — tok...