# MemoClaw

> Memory-as-a-Service API for AI agents. Store and recall memories using semantic vector search. No API keys — pay per request with USDC on Base via x402.

## API

- Base URL: https://api.memoclaw.com
- Authentication: x402 payment protocol (wallet address = identity)
- Free Tier: 100 free calls per wallet to paid endpoints (no payment required). Free endpoints don't count.
- Payment: USDC on Base after free tier (EIP-155:8453)
- Only endpoints using OpenAI (embeddings/LLM) are charged. Everything else is free.

## Paid Endpoints

- [POST /v1/store](/api-reference/store): Store a single memory ($0.005)
- [POST /v1/store/batch](/api-reference/store-batch): Store up to 100 memories ($0.04)
- [POST /v1/recall](/api-reference/recall): Semantic search across memories ($0.005)
- [PATCH /v1/memories/:id](/api-reference/update): Update a memory ($0.005)
- [PATCH /v1/memories/batch](/api-reference/update-batch): Batch update memories ($0.005)
- [POST /v1/ingest](/api-reference/ingest): Zero-effort ingestion — extract, dedup, auto-relate ($0.01)
- [POST /v1/memories/extract](/api-reference/extract): Extract structured facts from conversation ($0.01)
- [POST /v1/memories/consolidate](/api-reference/consolidate): Merge similar memories ($0.01)
- [POST /v1/context](/api-reference/context): Assemble context block ($0.01)
- [POST /v1/migrate](/api-reference/migrate): Import markdown files ($0.01)

## Free Endpoints

- [GET /v1/memories](/api-reference/list-memories): List memories with pagination (FREE)
- [GET /v1/memories/:id](/api-reference/get-memory): Get a single memory (FREE)
- [DELETE /v1/memories/:id](/api-reference/delete): Soft-delete a memory (FREE)
- [POST /v1/search](/api-reference/search): Full-text keyword search (FREE)
- [GET /v1/suggested](/api-reference/suggested): Proactive memory suggestions (FREE)
- [POST /v1/memories/:id/relations](/api-reference/relations): Create a relation (FREE)
- [GET /v1/memories/:id/relations](/api-reference/relations): List relations (FREE)
- [DELETE /v1/memories/:id/relations/:relationId](/api-reference/relations): Delete a relation (FREE)
- [GET /v1/memories/core](/api-reference/core-memories): Get core (pinned) memories (FREE)
- [POST /v1/memories/core](/api-reference/core-memories): Pin a core memory (FREE)
- [DELETE /v1/memories/core/:id](/api-reference/core-memories): Unpin a core memory (FREE)
- [GET /v1/memories/:id/history](/api-reference/memory-history): Memory change history (FREE)
- [GET /v1/memories/:id/graph](/api-reference/memory-graph): Traverse memory graph (FREE)
- [GET /v1/namespaces](/api-reference/namespaces): List namespaces (FREE)
- [GET /v1/export](/api-reference/export): Export memories (FREE)
- [GET /v1/stats](/api-reference/stats): Usage statistics (FREE)
- [DELETE /v1/memories](/api-reference/delete): Bulk delete memories (FREE)
- [GET /v1/free-tier/status](/api-reference/free-tier): Check free tier remaining (FREE)
- [GET /v1/free-tier/info](/api-reference/free-tier): Free tier policy info (FREE)
- [POST /auth/session](/api-reference/session): Exchange signature for JWT (FREE)
- [GET /health](/api-reference/health): Health check (FREE)

## Documentation

### Get Started
- [Introduction](/get-started/introduction)
- [Quickstart](/get-started/quickstart)
- [Authentication (x402)](/get-started/authentication)
- [Recipes](/get-started/recipes)
- [CLI Reference](/get-started/cli)
- [Python SDK](/get-started/python-sdk)
- [TypeScript SDK](/get-started/typescript-sdk)

### Concepts
- [How Memory Works](/concepts/how-memory-works)
- [Architecture](/concepts/architecture)
- [x402 Payment Flow](/concepts/x402-payment-flow)

### Guides
- [Migrate from OpenClaw](/guides/migrate-from-openclaw)
- [Migrate from Mem0](/guides/migrate-from-mem0)
- [Migrate from Zep](/guides/migrate-from-zep)
- [User Preferences](/guides/user-preferences)
- [Session Context](/guides/session-context)
- [Multi-Agent Memory](/guides/multi-agent)

### Integrations
- [OpenClaw Hooks](/openclaw-hooks)
- [MCP Integration](/mcp-integration)

### Reference
- [Pricing](/reference/pricing)
- [Input Limits](/reference/input-limits)
- [Rate Limiting](/reference/rate-limiting)
- [Error Codes](/reference/error-codes)
- [Changelog](/changelog)

## Key Concepts

- Embeddings: OpenAI text-embedding-3-small, 512 dimensions
- Index: HNSW (PostgreSQL pgvector)
- Scoring: hybrid = vector_sim × 0.55 + keyword_match × 0.25 + recency × 0.20; score = hybrid × context_importance × access_boost × type_decay
- Identity: EVM wallet address extracted from x402 payment proof
- Soft delete: deleted_at column, excluded from queries