clawmem

ClawMem 🦞

The "Sovereign Memory" for Low-Cost AI Agents.

🇨🇳 中文文档

💡 Why ClawMem?

Running a smart AI Agent usually requires a Vector Database and an Embedding Model. But for personal agents running on cheap VPS ($5/mo), this is a nightmare:

ClawMem is designed to be the lightest, most resilient memory layer for your sovereign AI agent.

✨ Key Features

• 🪶 Featherlight — Pure Go, statically compiled. Single binary ~15MB, memory usage <20MB. Runs on the cheapest VPS.
• 💰 Zero Cost Embeddings — Cloudflare Workers AI free tier provides high-quality semantic understanding at no cost.
• 🛡️ Bulletproof Resilience — 3-tier automatic fallback: Cloudflare → OpenAI Compatible → Local model. Never crashes, never stops.
• ⚡ Smart Caching — Built-in SQLite semantic cache with partial cache hit (diff) logic. Repeated text = zero API calls.
• 🔄 Batch Processing — Native batch embedding support to minimize HTTP roundtrips.
• 🔌 MCP Protocol — Built-in MCP server for seamless integration with Claude Desktop, OpenClaw, and other MCP clients.
• 🧠 Lazy Loading — Local model loads only when needed, keeping memory footprint minimal during cloud-first operation.
• 🏥 Health Checks — Automatic provider health checks on startup. Unhealthy providers are marked down immediately.

🏗️ Architecture

graph TD
    User[OpenClaw / MCP Client] -->|Store / Search| API[HTTP API :8090]
    User -->|MCP Protocol| MCP[MCP Server :stdio]
    API --> Service[Core Service]
    MCP --> Service
    Service -->|Text Data| SQLite[(SQLite DB<br/>Raw Text + Cache)]
    Service -->|Get Vector| Manager[Embedding Manager]
    
    subgraph "Multi-Tier Embedding Strategy"
        Manager -->|"Tier 1 · Priority"| CF[☁️ Cloudflare Workers AI<br/>Free · Fast]
        Manager -->|"Tier 1 · Alternate"| OA[🤖 OpenAI Compatible<br/>SiliconFlow etc.]
        Manager -->|"Tier 0 · Fallback"| Local[💻 Local BERT<br/>Lazy Loaded · Offline]
    end
    
    Manager -->|Vector Data| VectorDB[(Chromem-go<br/>Vector Store)]
    
    style CF fill:#f9f,stroke:#333
    style OA fill:#ffc,stroke:#333
    style Local fill:#cfc,stroke:#333
    style VectorDB fill:#bbf,stroke:#333

⚡ Quick Start

Option 1: Download Pre-built Binary

Download the latest alpha release from GitHub Releases.

# Linux (amd64)
chmod +x clawmem-linux-amd64
./clawmem-linux-amd64

# macOS (Apple Silicon)
chmod +x clawmem-darwin-arm64
./clawmem-darwin-arm64

Option 2: Build from Source

git clone https://github.com/xiaotiyanlove-star/clawmem.git
cd clawmem
CGO_ENABLED=0 go build -o clawmem ./cmd/server/
./clawmem

Option 3: One-Click Server Deployment

git clone https://github.com/xiaotiyanlove-star/clawmem
cd clawmem
sudo ./scripts/install.sh

The script will interactively configure the service port, database paths, and Cloudflare credentials, then automatically compile and register a systemd service.

🔧 Configuration

Configuration is done via environment variables or a .env file. See .env.example for a complete template.

Core

Embedding Strategy

Available strategies:

Provider Credentials

LLM (Optional)

📡 API Reference

Store a Memory

curl -X POST http://localhost:8090/api/memory \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user-001",
    "content": "The server IP address is 192.168.1.100"
  }'

Search Memories

curl "http://localhost:8090/api/memory/search?user_id=user-001&q=server+IP&top_k=3"

Health Check

curl http://localhost:8090/health

🔌 Integration

MCP Server (Claude Desktop / OpenClaw)

ClawMem includes a built-in MCP server binary (clawmem-mcp) for integration with MCP-compatible clients.

{
  "mcpServers": {
    "clawmem": {
      "command": "/path/to/clawmem-mcp",
      "args": [],
      "env": {
        "CLAWMEM_URL": "http://localhost:8090"
      }
    }
  }
}

OpenClaw Skill Mode

1. Copy the skills/clawmem directory to your OpenClaw skills folder.
2. Install dependencies: pip install requests.
3. Your agent can now say: "Remember that the server IP is 1.2.3.4" → Automatically stored via ClawMem.

🗺️ Roadmap

• Multi-tier embedding with automatic fallback
• SQLite semantic caching with partial cache hit diffing
• Batch embedding support
• MCP protocol server
• Lazy loading for local models
• Startup health checks
• ONNX Runtime integration for quantized local inference (Int8)
• Multi-user access control
• Memory expiration and lifecycle management

📄 License

This project is licensed under the MIT License.

🙏 Acknowledgements

This project references and draws inspiration from the architectural design of MemOS — an excellent AI memory operating system for LLM and Agent systems.

ClawMem is a lightweight implementation and adaptation based on MemOS design philosophy, customized specifically for the OpenClaw agent ecosystem.

Thanks to the MemTensor team for their outstanding work. 🫡