ClawMem: Intelligent Hybrid Agent Memory for OpenClaw

Purpose and Significance

ClawMem is a production-ready memory system that transforms unstructured markdown notes, project documentation, and research into an intelligent context layer for Claude Code and OpenClaw agents. Unlike naive retrieval approaches, ClawMem combines five complementary search and ranking strategies—BM25 full-text search, vector similarity, reciprocal rank fusion, query expansion, and cross-encoder reranking—into a unified hybrid system. It then layers composite scoring that accounts for recency decay, confidence signals, and content-type half-lives, enabling agents to surface deeply relevant context without prompt injection vulnerabilities or redundant context window waste.

Key Features

Hybrid Search Backend (QMD Fork) — Combines BM25 lexical search, 768-dimensional vector embeddings, query expansion, and reciprocal rank fusion with cross-encoder reranking for multi-modal relevance ranking.
Multi-Graph Memory Layer — Maintains semantic graphs (vector similarity), temporal backbone (chronological ordering), and causal graphs (LLM-inferred cause-effect chains) with adaptive beam search traversal.
SAME-Derived Composite Scoring — Weighs search relevance, recency decay, and confidence signals to surface context that ages naturally without manual curation.
Intent-Aware Query Classification — Automatically detects WHY, WHEN, ENTITY, and WHAT queries to adjust search strategy weights in real time.
A-MEM Self-Evolving Notes — Automatically enriches memory metadata with keywords, tags, contextual descriptions, and inter-document link generation as new documents interact with existing ones.
Session Bootstrapping — Injects user profile, latest handoff notes, recent decisions, and flagged stale content on session start without explicit prompting.
Decision Extraction and Handoff Generation — Observes session transcripts via local GGUF models, captures architectural decisions, and generates handoff summaries so subsequent sessions pick up context seamlessly.
Causal Inference — Infers causal relationships between facts extracted from session observations, building cause-effect chains that improve long-term memory coherence.
Hook-Based Integration — Integrates directly into Claude Code's hook system (context-surfacing, session-bootstrap, stop handlers) without API keys or cloud dependencies.
Prompt Injection Guarding — Sanitizes all surfaced content before injection to prevent adversarial memory poisoning.
Issue Tracker Sync — Indexes project issues from Beads issue trackers into the searchable memory vault for integrated project context.

Architecture Overview

ClawMem runs as a three-layer system within Claude Code's execution environment:

Layer 1: Intent-Aware Search — Classifies user query intent, weights search strategies accordingly, expands queries semantically, and reranks results via cross-encoder.
Layer 2: Multi-Graph Traversal — Routes queries through semantic, temporal, and causal graphs using adaptive beam search to capture both direct and indirect relevance.
Layer 3: QMD Search Backend — Executes hybrid retrieval on SQLite with FTS5 full-text indexing, sqlite-vec 768-dimensional vector storage, and configurable RRF fusion (k=60).

All context injection flows through Claude Code's hook system—no external services, no API key management, fully local operation with optional remote GPU support.

Getting Started

Prerequisites: Bun v1.0+, SQLite with FTS5 support (included with Bun), and optional GPU acceleration via llama-server (llama.cpp).

Installation (one command):

git clone https://github.com/yoloshii/clawmem.git ~/clawmem && cd ~/clawmem && bun install && ln -sf ~/clawmem/bin/clawmem ~/.bun/bin/clawmem

Bootstrap a vault:

./bin/clawmem bootstrap ~/notes --name notes

This single command initializes the vault, indexes documents, embeds vectors, installs Claude Code hooks, and registers the Model Context Protocol (MCP) server. For step-by-step setup, ClawMem offers granular commands: init, collection add, update --embed, setup hooks, and setup mcp.

OpenClaw Integration: Memory System Configuration

Option 1: ClawMem Exclusive (Recommended)

Disable OpenClaw's native memory initialization and route all memory operations through ClawMem:

openclaw config set agents.defaults.memorySearch.extraPaths ""

This approach achieves 90% automatic memory injection via hooks (profile, handoff, decisions, context-surfacing, stale-note flagging) and 10% agent-initiated MCP queries, with zero context duplication overhead.

Option 2: Hybrid Mode

Keep both ClawMem and OpenClaw native memory active for redundant recall: openclaw config set agents.defaults.memorySearch.extraPaths '[path]'. Tradeoff: redundant recall versus 10-15% context window waste and dual index maintenance.

GPU Services and Performance

ClawMem runs three lightweight llama-server (llama.cpp) instances totaling ~4.5GB VRAM: Embedding service (400MB, granite-embedding-278m for vector indexing), LLM service (2.2GB, qmd-query-expansion for intent classification and A-MEM enrichment), and Reranker service (1.3GB, qwen3-reranker for cross-encoder ranking). These fit comfortably on modern NVIDIA GPUs alongside other workloads. Remote GPU support is available via environment variables (CLAWMEM_EMBED_URL, CLAWMEM_LLM_URL, CLAWMEM_RERANK_URL).

Who It's For

Claude Code and OpenClaw Users — Teams using OpenClaw for AI-driven code generation who need persistent, intelligent memory across sessions.
Research and Documentation-Heavy Teams — Organizations with large markdown-based knowledge bases (design docs, research notes, architectural decisions) seeking automatic indexing and retrieval.
Local-First and Privacy-Conscious Developers — Those requiring fully local context processing without cloud dependency or API key exposure.
Graph-Oriented Memory Researchers — Practitioners exploring multi-graph memory architectures, causal inference, and intent-driven search strategies.

Project Composition

ClawMem comprises ~12,700 lines of TypeScript across 30 source files with 103 integration tests, built on Bun runtime. The codebase is actively maintained (last update February 2026) with no external cloud dependencies and no license restrictions.

Resources

GitHub Repository — Source code, issue tracker, and setup documentation.
README.md — Comprehensive architecture diagrams, CLI reference, and configuration guide.
AGENTS.md — Agent system documentation and hook integration details.
CLAUDE.md — Claude Code integration guide and memory operation flows.

Source: ClawMem GitHub repository (yoloshii/clawmem), accessed February 2026.

Read original