Memory Claw

Name: Memory Claw
Rating: 3.5 (1 reviews)
Author: duan78

By duan78 👁 33 views ▲ 0 votes

OpenClaw plugin - capture et rappel de mémos en français via LanceDB + Mistral Embeddings

GitHub

Install

npm install
```

Configuration Example

{
  "plugins": {
    "entries": {
      "memory-claw": {
        "config": {
          "enabled": true,
          "embedding": {
            "apiKey": "your-mistral-api-key",
            "model": "mistral-embed",
            "baseUrl": "https://api.mistral.ai/v1",
            "dimensions": 1024
          },
          "dbPath": "~/.openclaw/memory/memory-claw",
          "locales": ["fr", "en"],
          "maxCapturePerTurn": 5,
          "captureMinChars": 20,
          "captureMaxChars": 3000,
          "recallLimit": 5,
          "recallMinScore": 0.3,
          "enableStats": true,
          "gcInterval": 86400000,
          "gcMaxAge": 2592000000,
          "rateLimitMaxPerHour": 10,
          "enableWeightedRecall": true,
          "enableDynamicImportance": true
        }
      }
    }
  }
}

README

# Memory Claw v2.2.0

**A 100% autonomous multilingual memory plugin for OpenClaw with LanceDB + Mistral Embeddings.**

Memory Claw is an intelligent memory capture and recall system that automatically stores important information from your conversations and makes it available via semantic search. It manages its own database, configuration, and tools—completely independent from OpenClaw's core memory system.

## Overview

Memory Claw exists to solve a fundamental problem: **AI assistants forget everything between conversations**. Each new session starts from scratch, without context or memory from previous exchanges.

This plugin:
- **Automatically captures** important information from your conversations
- **Stores memories** in a local vector database (LanceDB)
- **Recalls relevant context** at the start of each conversation
- **Survives OpenClaw updates** (100% autonomous)

### Why Memory Claw?

Unlike the built-in `memory-lancedb` plugin, Memory Claw is:
- **Autonomous**: Manages its own DB, config, and tools
- **Persistent**: Survives OpenClaw updates without data loss
- **Intelligent**: Dynamic importance scoring, weighted recall, injection detection
- **Multilingual**: Supports French, English, Spanish, and German
- **Complete**: Full CLI, export/import, GC, statistics

---

## Features

### Multilingual Support (v2.2.0)

Memory Claw supports four languages with automatic detection:
- **French (fr)**: Primary language with most complete patterns
- **English (en)**: Full support for English conversations
- **Spanish (es)**: Spanish language patterns
- **German (de)**: German language patterns

The plugin automatically detects the language of each message and applies the appropriate patterns for capture and categorization. Configure active locales using the `locales` parameter in your config.

### Dynamic Importance Calculation

Each memory receives a score (0-1) calculated dynamically based on:

- **Category**: entity (0.9), decision (0.85), preference (0.7), technical (0.65), etc.
- **Source**: manual (0.9), agent_end (0.7), session_end (0.6), auto-capture (0.6)
- **Length**: Bonus for concise texts (20-200 characters)
- **Keywords**: Bonus for "important", "essential", "always", "never"
- **Density**: Bonus for proper names, dates, numbers
- **Penalties**: Questions, vague expressions ("I think", "maybe")

### Weighted Intelligent Recall

The recall system combines three factors for optimal results:

- **Semantic Similarity (60%)**: Vector proximity
- **Importance (30%)**: Memory importance score
- **Recency (10%)**: Age of memory (decays over 90 days)

A diversity penalty is applied to frequently recalled memories to avoid redundancy.

### Multi-Message Context Capture

Consecutive user messages are intelligently grouped:
- Semantic similarity detection between messages
- Groups messages sharing >30% significant words
- Captures complete context instead of fragments

### Prompt Injection Hardening

Advanced protection against prompt injection attacks:
- Detection of injection patterns (French + English)
- Filtering of system commands (exec, eval, $_GET)
- HTML escaping of injected content
- Suspicion warnings in logs

### Rate Limiting

Protection against overload:
- Configurable limit (default: 10 captures/hour)
- High-importance memories (>0.8) bypass limits
- Real-time tracking via CLI

### Automatic Garbage Collection

- Configurable interval (default: 24 hours)
- Deletes memories: age >30 days + importance <0.5 + hitCount <3
- Initial GC runs 1 minute after startup
- Preserves important or frequently used memories

### Persistent Statistics

- Tracks captures, recalls, and errors
- Persisted in `~/.openclaw/memory/memory-claw-stats.json`
- Survives restarts
- Logged every 5 minutes during activity

### Export/Import JSON

- Full export with metadata
- Smart import with deduplication
- Versioned format for future compatibility

### Migration from memory-lancedb

- Automatic migration from `memory-lancedb` (table `memories` → `memories_claw`)
- Detection and preservation of existing memories
- Deduplication during migration

### Hit Tracking

- Tracks how often each memory is recalled
- Used in diversity penalty for recall
- Factor in garbage collection decisions

### Hybrid Deduplication

Combines two methods for robust duplicate detection:
- **Vector Similarity**: Semantic similarity via embeddings
- **Text Similarity**: Direct text comparison (>85% = duplicate)

---

## Installation

### 1. Clone the Plugin

```bash
cd ~/.openclaw/workspace/plugins
git clone https://github.com/duan78/memory-claw.git
cd memory-claw
npm install
```

### 2. Configure OpenClaw

Add to your `openclaw.json` file:

```json
{
  "plugins": {
    "entries": {
      "memory-claw": {
        "config": {
          "enabled": true,
          "embedding": {
            "apiKey": "your-mistral-api-key",
            "model": "mistral-embed",
            "baseUrl": "https://api.mistral.ai/v1",
            "dimensions": 1024
          },
          "dbPath": "~/.openclaw/memory/memory-claw",
          "locales": ["fr", "en"],
          "maxCapturePerTurn": 5,
          "captureMinChars": 20,
          "captureMaxChars": 3000,
          "recallLimit": 5,
          "recallMinScore": 0.3,
          "enableStats": true,
          "gcInterval": 86400000,
          "gcMaxAge": 2592000000,
          "rateLimitMaxPerHour": 10,
          "enableWeightedRecall": true,
          "enableDynamicImportance": true
        }
      }
    }
  }
}
```

### 3. Restart OpenClaw

```bash
# If OpenClaw is running
openclaw stop
openclaw start
```

---

## Configuration

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `enabled` | boolean | `true` | Enable or disable the plugin |
| `embedding.apiKey` | string | **required** | Mistral API key (or via `MISTRAL_API_KEY` env var) |
| `embedding.model` | string | `"mistral-embed"` | Embedding model to use |
| `embedding.baseUrl` | string | `"https://api.mistral.ai/v1"` | Base URL for embedding API |
| `embedding.dimensions` | number | `1024` | Vector dimension for embeddings |
| `locales` | string[] | `["fr", "en"]` | Active locales (fr, en, es, de) |
| `dbPath` | string | `"~/.openclaw/memory/memory-claw"` | Path to LanceDB database |
| `maxCapturePerTurn` | number | `5` | Maximum memories captured per turn |
| `captureMinChars` | number | `20` | Minimum text length for capture |
| `captureMaxChars` | number | `3000` | Maximum text length for capture |
| `recallLimit` | number | `5` | Maximum memories recalled |
| `recallMinScore` | number | `0.3` | Minimum similarity score for recall (0-1) |
| `enableStats` | boolean | `true` | Enable statistics and detailed logs |
| `gcInterval` | number | `86400000` | GC interval in ms (default: 24h) |
| `gcMaxAge` | number | `2592000000` | Maximum memory age in ms (default: 30 days) |
| `rateLimitMaxPerHour` | number | `10` | Maximum captures per hour |
| `enableWeightedRecall` | boolean | `true` | Enable weighted scoring for recall |
| `enableDynamicImportance` | boolean | `true` | Enable dynamic importance calculation |

---

## Tools

The plugin registers 6 tools that can be used by the AI agent:

### memory_store

Manually store a memo in memory.

**Parameters:**
- `text` (string, required): Text content to store
- `importance` (number, optional): Importance score 0-1 (default: auto-calculated)
- `category` (string, optional): Category (preference, decision, entity, seo, technical, workflow, debug, fact)

**Example:**
```
User: Note that I prefer working with TypeScript rather than JavaScript
→ Agent calls memory_store with the text
→ Result: "Stored: 'I prefer working with TypeScript...' (id: xxx, category: preference, importance: 0.75)"
```

### memory_recall

Search stored memories by semantic similarity with weighted scoring.

**Parameters:**
- `query` (string, required): Search query
- `limit` (number, optional): Max results (default: 5)

**Example:**
```
User: What are my technical preferences?
→ Agent calls memory_recall with "technical preferences"
→ Result: "Found 3 memories: 1. [preference] I prefer TypeScript... (score: 85%, importance: 75%)"
```

### memory_forget

Delete a stored memory by ID or by query.

**Parameters:**
- `memoryId` (string, optional): Specific memory ID to delete
- `query` (string, optional): Query to find memories to delete

**Example:**
```
User: Forget everything I told you about my old project
→ Agent calls memory_forget with query="old project"
→ Result: "Deleted 3 memories matching query."
```

### memory_export

Export all stored memories to a JSON file for backup.

**Parameters:**
- `filePath` (string, optional): Custom file path (default: auto-generated)

**Example:**
```
→ Exports to ~/.openclaw/memory/memory-claw-backup-1234567890.json
```

### memory_import

Import memories from a JSON file.

**Parameters:**
- `filePath` (string, required): Path to the JSON file to import

**Example:**
```
→ Imports from file, deduplicates, and reports imported/skipped count
```

### memory_gc

Run garbage collection to remove old, low-importance memories.

**Parameters:**
- `maxAge` (number, optional): Max age in ms (default: 30 days)
- `minImportance` (number, optional): Min importance (default: 0.5)
- `minHitCount` (number, optional): Min hit count (default: 3)

**Example:**
```
→ Removes old, unimportant, rarely-used memories
```

---

## CLI Commands

The plugin registers 6 CLI commands:

### openclaw memory-fr list

List stored memories with optional filtering.

**Options:**
- `--category`: Filter by category
- `--limit`: Max results (default: 20)
- `--json`: Output as JSON

**Example:**
```bash
openclaw memory-fr list --category preference --limit 10
openclaw memory-fr list --json
```

### openclaw memory-fr search <query>

Search memories by semantic similarity.

**Options:**
- `--limit`: Max results (default: 10)

**Example:**
```bash
openclaw memory-fr search "TypeScript preferences"
openc

... (truncated)

tools