MemClawz

AI agent fleet memory system — Qdrant + Mem0 + Neo4j/Graphiti. Composite scoring, compaction engine, temporal knowledge graph, multi-claw federation, sleep-t...

Security Scan

The skill mostly does what its description says (a fleet memory system) but there are several mismatches and operational risks you should understand before installing — notably missing declared env vars, an install script that pulls and runs external code, and a federation feature that can transmit private memories to remote nodes.

Purpose & Capability

The name/description (MemClawz: Qdrant + embeddings + Neo4j temporal graph + federation) aligns with the runtime instructions and API endpoints. Requesting OpenAI and Anthropic keys (embeddings + classification) is coherent with the stated purpose. However, the registry metadata claims no required environment variables while the SKILL.md clearly requires OPENAI_API_KEY and ANTHROPIC_API_KEY (and other config values), which is an inconsistency between what the skill declares and what it actually needs.

Instruction Scope

The README instructs copying systemd service files, enabling persistent user services, cloning a GitHub repo, starting Qdrant/Neo4j, and configuring federation (push/pull of memories to arbitrary node URLs). Those actions access user filesystem, run background processes, and enable cross-node memory exchange — all expected for a memory system but potentially dangerous if you connect to untrusted nodes or run code without inspection. The SKILL.md also suggests reading local canonical files (MEMORY.md, memory/*.md), which is appropriate to the feature but means the skill will read potentially sensitive local data.

Install Mechanism

There is no registry install spec, but the packaged scripts/install.sh clones https://github.com/yoniassia/memclawz and may download Qdrant from GitHub releases. Pulling and executing code from an external GitHub repo and extracting a downloaded binary is a moderate-risk install pattern (external code execution). The URLs used are standard (GitHub), not obscure shorteners or IP-only installs, but you should review the remote repo and service files before running.

Credentials

The skill requires API keys (OpenAI for embeddings and Anthropic for classification) and other configuration (QDRANT/NEO4J connection settings) in practice, but the registry metadata lists no required env vars. The env keys requested by the instructions are proportional to the feature set, but the metadata omission is misleading and could cause surprise when installing. Federation examples also show 'node_key' secrets used to authorize remote nodes — sharing these or receiving them from untrusted parties can expose private memories.

Persistence & Privilege

The skill does not set always:true and allows model invocation (normal). However, installation instructions copy systemd service files and enable persistent user services (memclawz-api, memclawz-watcher, optionally neo4j). That creates long-running background processes and persistent network endpoints bound to localhost (or remote endpoints if misconfigured). This persistence is expected for a memory service but increases blast radius if the code or config is malicious or misconfigured.

What to consider before installing

Before installing or enabling MemClawz: (1) Review the GitHub repo (https://github.com/yoniassia/memclawz) and any systemd service files the package installs — do not blindly run the install script. (2) Expect to provide OpenAI and Anthropic API keys and to run Qdrant/Neo4j; the registry metadata incorrectly omits these requirements. (3) Treat federation features as high-risk: only register or accept remote nodes you trust, and inspect how node_key authentication is handled. (4) Run the installation in an isolated environment (VM or container) first if you want to evaluate behavior. (5) If you plan to keep it long-term, lock the service to localhost, restrict file permissions for memory storage, and rotate any shared secrets. If you want, I can list specific files/lines to inspect in the GitHub repo or help craft a safe installation checklist.

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

# 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

cd ~
git clone https://github.com/yoniassia/memclawz.git
cd memclawz
pip3 install -r requirements.txt

Configure

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

cp ~/memclawz/systemd/*.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now neo4j memclawz-api memclawz-watcher memclawz-cron

Verify

curl http://localhost:3500/health
# {"status":"ok","version":"6.0.0","qdrant":"ok","neo4j":"ok","graphiti":"ok","federation":"ok",...}

API Reference

Core (v5 compatible)

# 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)

# 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)

# Trigger session compaction
curl -X POST "http://localhost:3500/api/v1/compact/session" \
  -H "Content-Type: application/json" \
  -d '{"session_id":"main:whatsapp:direct:[phone]","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)

# 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)

# 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

{
  "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