Architecture Overview

​

System Architecture

​

Components

​

API Server

The MemoClaw API runs on Hono with Bun as the runtime. It handles:

• Request validation and rate limiting
• Wallet authentication (free tier) and x402 payment verification
• Memory CRUD operations
• LLM-powered extraction and consolidation
• Hybrid recall scoring

​

Database: PostgreSQL + pgvector

All memories are stored in PostgreSQL with the pgvector extension:

• Memory content stored as text with full-text search (tsvector)
• Embeddings stored as 512-dimensional vectors
• HNSW index for fast approximate nearest neighbor search
• GIN index on tsvector for keyword/BM25 matching

​

Embeddings

Text is converted to vectors using OpenAI’s text-embedding-3-small model (512 dimensions). An LRU cache of 1,000 embeddings avoids redundant API calls for repeated queries.

​

Payment Layer: x402

MemoClaw uses the x402 protocol for payment-as-authentication:

1. Free tier: Wallet signature verification (100 free calls)
2. Paid tier: USDC micropayments on Base (chain ID 8453) via EIP-3009 or Permit2
3. Identity: Your wallet address is extracted from the payment proof — no accounts needed

The x402 facilitator (Coinbase) verifies payments before requests are processed.

​

LLM Processing

Some endpoints use an LLM (OpenAI GPT) for intelligent processing:

• Extract (/v1/memories/extract): Parses conversations into discrete facts
• Ingest (/v1/ingest): Extracts, deduplicates, and relates facts
• Consolidate (/v1/memories/consolidate, LLM mode): Synthesizes merged memories

​

Data Flow: Store

1. Client sends memory content + metadata
2. API validates input, verifies payment/auth
3. Content is embedded via OpenAI (or cache hit)
4. Deduplication check: cosine similarity ≥ 0.95 against existing memories
5. Memory + embedding stored in PostgreSQL
6. Response with UUID returned

​

Data Flow: Recall

1. Client sends natural language query
2. Query embedded via OpenAI (or cache hit)
3. pgvector HNSW index finds nearest vectors
4. Full-text search (BM25) runs in parallel
5. Results scored with 4-signal hybrid formula:
   • Vector similarity (55%)
   • Keyword match (25%)
   • Recency decay (20%)
   • Multiplied by importance, access boost, and type decay
6. Top-K results returned with signal breakdown

​

Data Isolation

All data is scoped by wallet address. Wallet A cannot access Wallet B’s memories. Namespaces provide additional isolation within a single wallet.

​

Deployment

MemoClaw runs as a single stateless API server. The only stateful component is PostgreSQL. This makes horizontal scaling straightforward — add more API instances behind a load balancer.