memory-tools

# Memory Tools v2

Agent-controlled persistent memory for OpenClaw.

## What's New in v2

- **File-based storage** — Memories stored as readable markdown files
- **No external APIs** — No OpenAI dependency, everything runs locally
- **QMD search (optional)** — BM25 + vector + reranking via local GGUF models
- **Auto-migration** — Seamlessly upgrades from v1 SQLite/LanceDB storage

## Why Memory-as-Tools?

Traditional memory systems auto-capture everything, flooding context with irrelevant information. Memory Tools follows the [AgeMem](https://arxiv.org/abs/2409.02634) approach: **the agent decides** when to store and retrieve memories.

## Features

- **6 Memory Tools**: `memory_store`, `memory_update`, `memory_forget`, `memory_search`, `memory_summarize`, `memory_list`
- **Confidence Scoring**: Track how certain you are (1.0 = explicit, 0.5 = inferred)
- **Importance Scoring**: Prioritize critical instructions over nice-to-know facts
- **Decay/Expiration**: Temporal memories automatically become stale
- **Human-readable storage**: Markdown files with YAML frontmatter
- **Conflict Resolution**: New info auto-supersedes old (no contradictions)

## Installation

### Step 1: Install from ClawHub

```bash
clawhub install memory-tools
```

### Step 2: Build the plugin

```bash
cd skills/memory-tools
npm install
npm run build
```

### Step 3: Activate the plugin

```bash
openclaw plugins install --link .
openclaw plugins enable memory-tools
```

### Step 4: Restart the gateway

```bash
openclaw gateway restart
```

### Optional: Install QMD for better search

```bash
npm install -g @tobilu/qmd
```

Without QMD, basic filtering works. With QMD, you get semantic search (BM25 + vector + reranking).

### Node Compatibility (QMD)

- QMD may not be compatible with the newest Node ABI immediately.
- If QMD fails (for example `NODE_MODULE_VERSION` mismatch), memory-tools falls back to basic mode.
- To force basic mode: `MEMORY_TOOLS_DISABLE_QMD=true`.
- For best QMD stability, us...

<p align="center">
  <img src="header.png" alt="memory-tools" width="100%">
</p>

# OpenClaw Memory Tools v2

Agent-controlled memory plugin for OpenClaw with confidence scoring, decay, and semantic search.

## What's New in v2

- **File-based storage** - Memories stored as readable markdown files
- **No external APIs** - No OpenAI dependency, everything runs locally
- **QMD search (optional)** - BM25 + vector + reranking via local GGUF models
- **Auto-migration** - Seamlessly upgrades from v1 SQLite/LanceDB storage

## Why Memory-as-Tools?

Traditional AI memory systems auto-capture everything, flooding context with irrelevant information. **Memory-as-Tools** follows the [AgeMem](https://arxiv.org/abs/2409.02634) approach: the agent decides **when** to store and retrieve memories.

```
Traditional: Agent -> always retrieves -> context flooded
Memory-as-Tools: Agent -> decides IF/WHAT to remember -> uses tools explicitly
```

## Features

- **6 Memory Tools**: `memory_store`, `memory_update`, `memory_forget`, `memory_search`, `memory_summarize`, `memory_list`
- **Confidence Scoring**: Track how certain you are about each memory (1.0 = explicit, 0.5 = inferred)
- **Importance Scoring**: Prioritize critical instructions over nice-to-know facts
- **Decay/Expiration**: Temporal memories (events) automatically become stale
- **Human-readable storage**: Markdown files with YAML frontmatter
- **Semantic Search**: Optional QMD-powered hybrid search (BM25 + vector + reranking)
- **Zero External Dependencies**: Everything runs locally, no API keys needed
- **Standing Instructions**: Auto-inject category="instruction" memories at conversation start

## Installation

### Step 1: Install from ClawHub

```bash
clawhub install memory-tools
```

### Step 2: Build the plugin

```bash
cd skills/memory-tools
npm install
npm run build
```

### Step 3: Activate the plugin

```bash
openclaw plugins install --link .
openclaw plugins enable memory-tools
```

### Step 4: Restart the gateway...