MemClawz v11 🧠

MemClawz is a private memory API for AI agents. It provides fast semantic search, composite-scored retrieval, background enrichment, and automated compaction over a Qdrant vector store.

Designed for the OpenClaw ecosystem. Internal use only.

---

What's New in v11.2

• Write-only access tier for external fleet members (two-tier auth proxy)
• Rate limiting on auth proxy (5 failed attempts → 5-min block)
• Security hardening: token rotation, IP allowlist management
• Fleet sync compatibility: memclawz-sync cron module works with write-only tokens

What's New in v11

v11 is a ground-up strip to core essentials. 15,900+ lines removed, zero functionality loss for production workloads.

Performance

• 3.8× faster throughput end-to-end vs v10
• Dramatically better search quality — cleaner scoring, less noise
• Leaner memory footprint and faster cold starts

Architecture — stripped to core

v11 keeps only what matters:

Module	Purpose
api.py	FastAPI endpoints: search, add, memories, stats, compaction
config.py	Environment-based configuration
scoring.py	Composite scoring: semantic similarity + recency + type weight + frequency
enrichment.py	Async Gemini-powered memory enrichment
compactor.py	3-tier compaction: session → daily → weekly
qdrant_store.py	Qdrant operations, counters, dedup
classifier.py	Memory type classification
utils.py	Shared utilities
routing.py	Lightweight routing helpers (retained)
compaction_cron.py	Background compaction scheduler

Removed in v11

The following modules were deleted — they added complexity without production value:

• federation.py — cross-node memory exchange
• fleet_sync.py — routing tables, delegation, fleet coordination
• graphiti_layer.py — Neo4j/Graphiti temporal graph
• hybrid_search.py — multi-backend search fusion
• routing_audit.py — routing telemetry reports
• routing_crystallize.py — routing-aware crystallization
• reflection.py — sleep-time reflection
• self_links.py — self-referential memory links
• template_distributor.py — agent template distribution
• v7_extensions.py — legacy v7 compatibility
• lifecycle.py — 8-state memory lifecycle
• nightcron/ — nightly automation jobs
• mcp_server.py — MCP server
• pipelines.py — pipeline orchestration
• router.py — advanced routing engine
• contradiction.py, decay.py, importer.py, watcher.py
• templates/ — orchestrator and specialist bundles (15 agents)
• reports/ — routing audit reports

---

API

Method	Path	Purpose
GET	/health	Health + dependency status
GET	/api/v1/search	Semantic search with composite scoring
POST	/api/v1/add	Write with async enrichment
POST	/api/v1/add-direct	Direct write (no enrichment)
GET	/api/v1/memories	List/filter memories
GET	/api/v1/agents	Per-agent memory counts
GET	/api/v1/stats	Aggregate stats (cached)
DELETE	/api/v1/memory/{id}	Delete a memory
PUT	/api/v1/memory/{id}	Update a memory
POST	/api/v1/compact/session	Session compaction
POST	/api/v1/compact/daily	Daily digest compaction
POST	/api/v1/compact/weekly	Weekly merge compaction
GET	/api/v1/compact/status	Compaction status

Search (GET, not POST)

curl -s -G http://127.0.0.1:3500/api/v1/search \
  --data-urlencode 'q=deploy issue' \
  --data-urlencode 'limit=5' | jq

Write

curl -s -X POST http://127.0.0.1:3500/api/v1/add \
  -H 'Content-Type: application/json' \
  -d '{
    "content": "The v11 migration completed successfully.",
    "user_id": "admin",
    "agent_id": "main",
    "memory_type": "fact"
  }' | jq

---

Composite Scoring

Retrieval combines four signals:

1. Semantic similarity — vector cosine distance
2. Recency decay — newer memories score higher
3. Type-based importance — decision, preference, commitment resist decay
4. Access frequency — frequently-retrieved memories get boosted

---

3-Tier Compaction

Tier	Trigger	Effect
Session	End of agent session	Summarize session into durable outputs
Daily	Daily schedule	Digest recent operational memory
Weekly	Weekly schedule	Merge repeated patterns, reduce duplication

---

Quick Start

cd ~/memclawz
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# Configure
cp .env.example .env  # edit with your Qdrant host, API keys, etc.

# Run
python -m uvicorn memclawz.api:app --host 127.0.0.1 --port 3500

# Health check
curl -s http://127.0.0.1:3500/health | jq

---

Configuration

Primary config via environment (see memclawz/config.py):

Variable	Default	Purpose
QDRANT_HOST	localhost	Qdrant host
QDRANT_PORT	6333	Qdrant port
QDRANT_COLLECTION	memclawz_memories	Collection name
MEMCLAWZ_API_HOST	127.0.0.1	API bind address
MEMCLAWZ_API_PORT	3500	API port
MEMCLAWZ_API_KEYS	empty	Bearer tokens for remote auth
GEMINI_MODEL	gemini-2.5-flash-lite	Enrichment model

---

Authentication

• Local requests (127.0.0.1, ::1) bypass auth
• /health is always open
• Remote requests require Authorization: Bearer <token>
• Authenticated proxy available on port 13500

Write-Only Access Tier (v11.2)

External fleet members can be granted write-only tokens that allow adding memories but block all read/search/list/delete operations. This enables a two-tier auth model:

Tier	Permissions	Use Case
Full access	Read, write, search, list, delete, compact	Internal agents on trusted infrastructure
Write-only	POST /api/v1/add, POST /api/v1/add-direct only	External fleet members contributing memories

Security features (v11.2):

• Rate limiting on auth proxy — 5 failed auth attempts triggers a 5-minute IP block
• Token rotation — rotate tokens without downtime via config reload
• IP allowlist management — restrict proxy access to known IPs
• memclawz-sync cron module (v11.1) now works with write-only tokens for outbound sync

---

Fleet Sync (v11.1)

Lightweight cron-based memory sync between MemClawz instances. Replaces the old federation module.

# Install on any fleet node
cd ~/memclawz/sync
./install.sh          # interactive setup + cron

• Outbound: pushes new local memories to central
• Inbound: pulls cross-agent intelligence from central
• Dedup: skips already-synced memories
• Resilient: graceful on central downtime

See sync/README.md for full docs.

---

Repo Layout

memclawz/
├── memclawz/
│   ├── __init__.py
│   ├── api.py
│   ├── classifier.py
│   ├── compactor.py
│   ├── compaction_cron.py
│   ├── config.py
│   ├── enrichment.py
│   ├── qdrant_store.py
│   ├── routing.py
│   ├── scoring.py
│   └── utils.py
├── sync/
│   ├── memclawz-sync.py
│   ├── install.sh
│   ├── README.md
│   └── .env (local config, gitignored)
├── docs/
├── .env
├── pyproject.toml
└── VERSION

---

License

MIT