OpenClaw Memory Tools

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

Why Memory-as-Tools?

Traditional AI memory systems auto-capture everything, flooding context with irrelevant information. Memory-as-Tools follows the AgeMem 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
• Semantic Search: Vector-based similarity search via LanceDB
• Hybrid Storage: SQLite (via WASM) for metadata + LanceDB for vectors
• Zero Native Dependencies: Uses sql.js (WASM) - no C++ compilation, works on any Node version
• Standing Instructions: Auto-inject category="instruction" memories at conversation start

Installation

Quick Install

# Clone to OpenClaw extensions directory
git clone https://github.com/purple-horizons/openclaw-memory-tools.git ~/.openclaw/extensions/memory-tools
cd ~/.openclaw/extensions/memory-tools

# Install dependencies and build
pnpm install && pnpm build

Configuration

Add to ~/.openclaw/openclaw.json:

{
  "plugins": {
    "slots": {
      "memory": "memory-tools"
    },
    "entries": {
      "memory-tools": {
        "enabled": true,
        "config": {
          "embedding": {}
        }
      }
    }
  },
  "tools": {
    "alsoAllow": ["group:plugins"]
  }
}

OpenAI API Key

The plugin needs an OpenAI API key for embeddings. Three options:

Option 1: Environment variable (recommended)

# Add to ~/.zshrc or ~/.bashrc
export OPENAI_API_KEY="sk-proj-..."

Option 2: Reference env var in config

{
  "embedding": {
    "apiKey": "${OPENAI_API_KEY}"
  }
}

Option 3: Direct in config (not recommended)

{
  "embedding": {
    "apiKey": "sk-proj-..."
  }
}

Verify Installation

# Restart gateway
openclaw gateway stop && openclaw gateway run

# Check plugin loaded
openclaw plugins list

# Test CLI
openclaw memory-tools stats

Memory Categories

Tool Reference

memory_store

Store a new memory.

memory_store({
  content: "User prefers bullet points",
  category: "preference",
  confidence: 0.9,      // How sure (0-1)
  importance: 0.7,      // How critical (0-1)
  decayDays: null,      // null = permanent
  tags: ["formatting"]
})

memory_update

Update an existing memory.

memory_update({
  id: "abc-123",
  content: "User prefers numbered lists",  // Optional
  confidence: 0.95                          // Optional
})

memory_forget

Delete a memory.

memory_forget({
  id: "abc-123",           // If known
  query: "bullet points",  // Or search
  reason: "User corrected"
})

memory_search

Semantic search.

memory_search({
  query: "formatting preferences",
  category: "preference",      // Optional filter
  minConfidence: 0.7,          // Optional filter
  limit: 10
})

memory_summarize

Get topic summary.

memory_summarize({
  topic: "user's work",
  maxMemories: 20
})

memory_list

Browse all memories.

memory_list({
  category: "instruction",
  sortBy: "importance",
  limit: 20
})

CLI Commands

# Show statistics
openclaw memory-tools stats

# List memories
openclaw memory-tools list --category preference

# Search memories
openclaw memory-tools search "dark mode"

# Export all memories as JSON
openclaw memory-tools export

Architecture

┌─────────────────────────────────────────────────────────┐
│                    OpenClaw Agent                        │
│                                                         │
│  Agent decides: "This is worth remembering"             │
│         ↓                                               │
│  Calls: memory_store(...)                               │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│                   Memory Tools                          │
├─────────────────────────────────────────────────────────┤
│  store │ update │ forget │ search │ summarize │ list   │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│                 Storage Layer                           │
│  ┌──────────────┐    ┌──────────────┐                  │
│  │ SQLite/WASM  │    │   LanceDB    │                  │
│  │  (metadata)  │◄──►│  (vectors)   │                  │
│  └──────────────┘    └──────────────┘                  │
└─────────────────────────────────────────────────────────┘

Development

# Install dependencies
pnpm install

# Run tests
pnpm test

# Run tests with coverage
pnpm test:coverage

# Type check
pnpm typecheck

# Build
pnpm build

Comparison with Other Memory Systems

Design Philosophy

Different memory systems optimize for different things:

• Automatic systems (memU, claude-mem) minimize agent cognitive load by extracting memories in the background. Trade-off: less control over what's captured, conflicts accumulate.

• Agent-controlled systems (memory-tools) put the agent in charge of what matters. Trade-off: requires active management, but memories are deliberate choices.

For agents that maintain ongoing relationships with users—where someone might say "no, my favorite color is purple, not blue"—explicit conflict handling prevents contradictory memories from accumulating. Every memory has a clear provenance: the agent decided it was worth remembering, and corrections replace rather than compete with old information.

The hybrid SQLite (WASM) + LanceDB storage means you can always sqlite3 ~/.openclaw/memory/tools/memory.db to inspect exactly what your agent knows and why.

References

• AgeMem Paper - Memory operations as first-class tools
• memU - Hierarchical memory with proactive context
• claude-mem - Hook-based automatic memory
• Mem0 - AI memory layer
• OpenClaw - Personal AI assistant

License

MIT - Purple Horizons