Skill: yoniassia/memclawz (version 6.0.1)

--- name: memclawz description: AI agent fleet memory system — Qdrant + Mem0 + Neo4j/Graphiti. Composite scoring, compaction engine, temporal knowledge graph, multi-claw federation, sleep-time reflection, routing engine, MCP server. Use when you need to install, configure, manage, search, route, compact, or upgrade the agent memory system. metadata: openclaw: requires: bins: ["python3", "pip3"] --- # MemClawz v6 🧠 Fleet memory system for OpenClaw agents with composite scoring, compaction engine, Graphiti temporal knowledge graph, multi-claw federation, and sleep-time reflection. ## What's New in v6 - **Composite Scoring** — Weighted blend of semantic similarity + recency decay + importance + access frequency - **Compaction Engine** — Session/daily/weekly compaction with LLM extraction - **Graphiti Integration** — Neo4j temporal knowledge graph for entity relationships and contradiction detection - **Multi-Claw Federation** — HTTP push/pull protocol for sharing memories across fleet - **Sleep-Time Reflection** — LLM-driven pattern detection, insight generation, and MEMORY.md update proposals - **Enhanced MCP Server** — New tools: compact_session, reflect, memory_stats ## Quick Install ### Prerequisites - Python 3.10+ - Qdrant running (Docker or binary) - Neo4j running (for Graphiti; optional but recommended) - OpenAI API key (for embeddings) - Anthropic API key (for classification) ### Install Qdrant ```bash # Docker (preferred) docker run -d --name qdrant -p 6333:6333 -p 6334:6334 \ -v ~/.openclaw/qdrant-storage:/qdrant/storage \ --restart unless-stopped qdrant/qdrant # Or binary (no Docker) curl -sL https://github.com/qdrant/qdrant/releases/latest/download/qdrant-x86_64-unknown-linux-musl.tar.gz | tar xz ./qdrant --storage-path ~/.openclaw/qdrant-storage & ``` ### Install MemClawz ```bash cd ~ git clone https://github.com/yoniassia/memclawz.git cd memclawz pip3 install -r requirements.txt ``` ### Configure ```bash cat > ~/memclawz/.env << EOF OPENAI_API_KEY=<your-key> ANTHROPIC_API_KEY=<your-key> QDRANT_HOST=localhost QDRANT_PORT=6333 QDRANT_COLLECTION=yoniclaw_memories NEO4J_URI=bolt://localhost:7687 NEO4J_USER=neo4j NEO4J_PASSWORD= GRAPHITI_ENABLED=true FEDERATION_ENABLED=true FEDERATION_ROLE=master WORKSPACE_DIR=/home/yoniclaw/.openclaw/workspace EOF ``` ### Deploy Services ```bash cp ~/memclawz/systemd/*.service ~/.config/systemd/user/ systemctl --user daemon-reload systemctl --user enable --now neo4j memclawz-api memclawz-watcher memclawz-cron ``` ### Verify ```bash curl http://localhost:3500/health # {"status":"ok","version":"6.0.0","qdrant":"ok","neo4j":"ok","graphiti":"ok","federation":"ok",...} ``` ## API Reference ### Core (v5 compatible) ```bash # Search with composite scoring curl "http://localhost:3500/api/v1/search?q=eToro+SuperApp&limit=10" # Use raw cosine: &use_composite=false # Add memory (feeds both Qdrant AND Graphiti) curl -X POST "http://localhost:3500/api/v1/add" \ -H "Content-Type: application/json" \ -d '{"content":"BTC hit 100K on March 1","agent_id":"tradeclaw","memory_type":"event"}' # List by agent curl "http://localhost:3500/api/v1/memories?agent_id=tradeclaw&limit=20" # Stats / Agents curl http://localhost:3500/api/v1/stats curl http://localhost:3500/api/v1/agents ``` ### Graph Search (v6) ```bash # Search temporal knowledge graph curl "http://localhost:3500/api/v1/graph/search?q=eToro+deployment" # Get entity relationships curl "http://localhost:3500/api/v1/graph/entity/YoniClaw" ``` ### Compaction (v6) ```bash # Trigger session compaction curl -X POST "http://localhost:3500/api/v1/compact/session" \ -H "Content-Type: application/json" \ -d '{"session_id":"main:whatsapp:direct:+35794329522","agent_id":"main"}' # Generate daily digest curl -X POST "http://localhost:3500/api/v1/compact/daily" # Run weekly merge curl -X POST "http://localhost:3500/api/v1/compact/weekly" # Check compaction status curl "http://localhost:3500/api/v1/compact/status" ``` ### Reflection (v6) ```bash # Trigger reflection (analyzes last 24h of memories) curl -X POST "http://localhost:3500/api/v1/reflect" \ -H "Content-Type: application/json" \ -d '{"hours":24,"max_memories":100}' ``` ### Federation (v6) ```bash # Register a remote node curl -X POST "http://localhost:3500/api/v1/federation/register" \ -H "Content-Type: application/json" \ -d '{"node_id":"clawdet","node_url":"http://188.34.197.212:3500","node_key":"shared-secret"}' # Push memories from remote curl -X POST "http://localhost:3500/api/v1/federation/push" \ -H "Content-Type: application/json" \ -d '{"node_id":"clawdet","node_key":"shared-secret","memories":[{"content":"...","type":"fact","agent":"main"}]}' # Pull memories to remote curl -X POST "http://localhost:3500/api/v1/federation/pull" \ -H "Content-Type: application/json" \ -d '{"node_id":"clawdet","node_key":"shared-secret","since":"2026-03-13T00:00:00Z","limit":100}' # Federation status curl "http://localhost:3500/api/v1/federation/status" ``` ## Composite Scoring ``` score = (w_semantic × similarity + w_recency × decay + w_importance × weight) × access_boost ``` - **Semantic**: 50% weight (cosine from Qdrant) - **Recency**: 30% weight (exponential, 90-day half-life) - **Importance**: 20% weight (type-based: decisions > preferences > facts > events) - **Access boost**: up to 1.5× for frequently accessed memories - **Persistent types** (decisions, preferences, relationships): 40% recency floor ## Memory Types - **fact** — factual statement about a person, project, system - **decision** — a choice that was made - **preference** — user preference or style choice - **procedure** — steps to accomplish something - **relationship** — info about a person or org relationship - **event** — something that happened at a specific time - **insight** — learned lesson, pattern, or strategic insight ## Canonical Memory Order 1. **Local canonical files first** — `MEMORY.md`, `memory/*.md`, `memory/people/*`, `memory/sessions/*`, `knowledge/*.md` 2. **MemClawz second** — Qdrant + Mem0 + Neo4j/Graphiti + API + MCP 3. **LCM/transcripts third** — raw capture and extraction layer ## Services | Service | Port | Description | |---------|------|-------------| | `memclawz-api` | 3500 | REST API (v6) | | `memclawz-watcher` | — | LCM auto-extract (+ Graphiti feed) | | `memclawz-cron` | — | Compaction scheduler (30-min cycle) | | `memclawz-mcp` | stdio | MCP server (v6 tools) | | Neo4j | 7474/7687 | Graph database (Graphiti) | | Qdrant | 6333 | Vector database | ## MCP Integration ```json { "mcpServers": { "memclawz": { "command": "python3", "args": ["/path/to/memclawz/memclawz/mcp_server.py"], "env": {"OPENAI_API_KEY": "<key>", "ANTHROPIC_API_KEY": "<key>"} } } } ``` MCP tools: search_memory, add_memory, get_agent_memories, compact_session, reflect, memory_stats ## Architecture ``` LCM → Watcher → Classify → Mem0 → Qdrant + Graphiti/Neo4j ↑↓ ↑↓ Fleet Agents ←→ REST API :3500 ←→ Qdrant Neo4j MCP Clients ←→ MCP Server ←→ Qdrant Remote Claws ←→ Federation API ←→ Qdrant Cron → Compactor/Reflection → Files + Qdrant + Graphiti ```

path: references/api-reference.md
content: # MemClawz v5 API Reference

Base URL: `http://localhost:3500`

## Health Check

```
GET /health
→ {"status": "ok", "version": "5.0.0"}
```

## Search Memories

```
GET /api/v1/search?q=<query>&user_id=yoni&agent_id=<agent>&memory_type=<type>&limit=20
→ {"results": [...], "count": N}
```

## Add Memory

```
POST /api/v1/add
Body: {"content": "...", "user_id": "yoni", "agent_id": "main", "memory_type": "fact", "metadata": {}}
→ Mem0 add result
```

## List Memories

```
GET /api/v1/memories?user_id=yoni&agent_id=<agent>&limit=50&offset=0
→ {"memories": [...], "total": N}
```

## List Agents

```
GET /api/v1/agents
→ {"agent_name": {"count": N, "types": {"fact": N, ...}}, ...}
```

## Stats

```
GET /api/v1/stats
→ {"total_memories": N, "by_type": {...}, "by_agent": {...}, "by_source": {...}}
```

## Delete Memory

```
DELETE /api/v1/memory/<memory_id>
→ {"status": "deleted"}
```

## Update Memory

```
PUT /api/v1/memory/<memory_id>
Body: {"content": "new content"}
→ {"status": "updated"}
```


path: references/architecture.md
content: # MemClawz v5 Architecture

## Overview

MemClawz is the memory layer for the YoniClaw AI agent fleet. It provides:
- **Auto-extraction** from LCM conversation summaries
- **Shared memory bus** via REST API
- **Typed classification** of memories (fact, decision, preference, etc.)
- **Contradiction detection** to identify superseded information
- **Relevance decay** scoring with time-based half-life
- **MCP server** for Model Context Protocol integration

## Data Flow

```
LCM Database (conversations)
    ↓ watcher (every 30 min)
    ↓ classify_memory()
    ↓
Mem0 (manages embeddings + metadata)
    ↓
Qdrant (vector storage)
    ↑
REST API ←→ All Agents (search, add, list)
    ↑
MCP Server ←→ MCP Clients (Claude Desktop, etc.)
```

## Components

| Component | File | Purpose |
|-----------|------|---------|
| Config | `config.py` | Centralized settings, credential loading |
| Watcher | `watcher.py` | LCM → Mem0 auto-extract pipeline |
| API | `api.py` | FastAPI shared memory bus (port 3500) |
| Classifier | `classifier.py` | Heuristic + LLM memory type classification |
| Contradiction | `contradiction.py` | Detect superseded/contradicting memories |
| Decay | `decay.py` | Time-based relevance scoring |
| MCP Server | `mcp_server.py` | Model Context Protocol integration |
| Importer | `importer.py` | Bulk import from markdown/sqlite/jsonl |

## Memory Types

| Type | Description | Decay Floor |
|------|-------------|-------------|
| decision | Choices made | 50% (persistent) |
| preference | User preferences | 50% (persistent) |
| relationship | People, contacts | 50% (persistent) |
| insight | Learned lessons | Normal |
| procedure | How-to / workflows | Normal |
| fact | General facts | Normal |
| event | Time-specific events | Normal |

## Storage

- **Vector DB**: Qdrant (localhost:6333, collection: `yoniclaw_memories`)
- **Embeddings**: OpenAI `text-embedding-3-small` (1536 dimensions)
- **LLM**: Anthropic Claude Sonnet for classification and memory extraction
- **State**: `~/.memclawz/last_sync.json` tracks watcher position


path: scripts/install.sh
content: #!/bin/bash
set -e
echo "🧠 Installing MemClawz v5..."

# Check prerequisites
command -v python3 >/dev/null || { echo "❌ python3 required"; exit 1; }
command -v pip3 >/dev/null || { echo "❌ pip3 required"; exit 1; }

# Clone or update repo
if [ -d ~/memclawz ]; then
    cd ~/memclawz && git pull
else
    cd ~ && git clone https://github.com/yoniassia/memclawz.git && cd memclawz
fi

# Install Python deps
pip3 install -r requirements.txt

# Check Qdrant
if curl -s http://localhost:6333/healthz >/dev/null 2>&1; then
    echo "✅ Qdrant running"
else
    echo "⚠️ Qdrant not running. Starting..."
    if command -v docker >/dev/null; then
        docker run -d --name qdrant -p 6333:6333 -p 6334:6334 \
            -v ~/.openclaw/qdrant-storage:/qdrant/storage \
            --restart unless-stopped qdrant/qdrant
    else
        echo "📥 Downloading Qdrant binary..."
        curl -sL https://github.com/qdrant/qdrant/releases/latest/download/qdrant-x86_64-unknown-linux-musl.tar.gz | tar xz -C ~/memclawz/
        nohup ~/memclawz/qdrant --storage-path ~/.openclaw/qdrant-storage > /tmp/qdrant.log 2>&1 &
    fi
    sleep 3
fi

# Deploy systemd services
mkdir -p ~/.config/systemd/user
cp ~/memclawz/systemd/*.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now memclawz-api memclawz-watcher

echo "✅ MemClawz v5 installed!"
echo "API: http://localhost:3500/health"
echo "Watcher: systemctl --user status memclawz-watcher"


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: suspicious | SkillSpector: suspicious (MEDIUM)