> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memoclaw.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture Overview

> How MemoClaw is built: API server, managed memory storage, embeddings, and payment layer.

<Info>
  MemoClaw is a managed memory service, not a general-purpose vector database. We run PostgreSQL + pgvector under the hood so you don't have to, but you can't use MemoClaw as a drop-in vector store.
</Info>

## System Architecture

```mermaid theme={null}
graph LR
  A["Your Agent\n(SDK / CLI / MCP)"] <--> B["MemoClaw API\n(Hono on Bun)"]
  B <--> C["PostgreSQL +\npgvector"]
  B --> D["OpenAI\nEmbeddings API"]
  B --> E["x402 Facilitator\n(Coinbase)"]
```

## Components

### API Server

The MemoClaw API runs on [Hono](https://hono.dev) with [Bun](https://bun.sh) 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](https://github.com/pgvector/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](https://x402.org) 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.

<CardGroup cols={2}>
  <Card title="How Memory Works" icon="brain" href="/concepts/how-memory-works">
    Deep dive into scoring, decay, and retrieval.
  </Card>

  <Card title="x402 Payment Flow" icon="wallet" href="/concepts/x402-payment-flow">
    Protocol-level details of payment-as-auth.
  </Card>
</CardGroup>