Architecture Overview

Route Handler (Hono)
  │
  ├── Validates request with Zod
  ├── Extracts user context from auth middleware
  │
  ▼
Service Layer
  │
  ├── Implements business logic
  ├── Calls database via withUserSchema(userId, async (tx) => {...})
  ├── Triggers async side effects (entity extraction, etc.)
  │
  ▼
Database (postgres.js + Drizzle)
  │
  ├── SET LOCAL search_path = 'user_abc123', public;
  ├── Execute queries within transaction
  └── Return typed results

// Example service function
async function getProfile(userId: string) {
  return withUserSchema(userId, async (tx) => {
    const [profile] = await tx`
      SELECT version, confidence, data, updated_at
      FROM profile
      ORDER BY version DESC
      LIMIT 1
    `;
    return profile;
  });
}

1. Memory Stored (store_memory / POST /v1/vectors/:collection)
   │
   ▼
2. Content embedded (text-embedding-3-small) → vector stored in pgvector
   │
   ▼
3. Async: Entity extraction triggered (background)
   │
   ├── Content sent to gpt-5-mini with structured output schema
   ├── Response parsed: entities[] with {name, type, properties}
   ├── Edges[] with {source, target, type, properties}
   │
   ▼
4. Deduplication
   │
   ├── For each extracted entity:
   │   ├── Fuzzy match against existing entities (pg_trgm similarity)
   │   ├── If match > 0.8: merge with existing entity
   │   └── If no match: create new entity
   │
   ├── For each extracted edge:
   │   ├── Check for existing edge with same source, target, type
   │   └── If exists: update properties; else: create new edge
   │
   ▼
5. Entity mentions recorded (links entity ↔ source vector entry)
   │
   ▼
6. Graph statistics updated

AI Agent (e.g., Claude Desktop)
  │
  │  MCP tool call: store_memory({content: "...", collection: "facts"})
  │  Transport: Streamable HTTP POST to /mcp
  │
  ▼
Hono Server
  │
  ├── 1. Parse MCP request, extract tool name + arguments
  ├── 2. Authenticate: validate MCP token → resolve user_id + agent_id
  ├── 3. Consent check: does this agent have 'vectors' write permission?
  │      └── If no: return CONSENT_REQUIRED error
  ├── 4. Rate limit check: is this agent under its request quota?
  │      └── If no: return RATE_LIMITED error
  │
  ▼
MCP Tool Handler (store_memory)
  │
  ├── 5. Validate arguments with Zod schema
  ├── 6. Call VectorService.store(userId, content, collection, metadata)
  │
  ▼
Vector Service
  │
  ├── 7. Generate embedding via OpenAI text-embedding-3-small
  ├── 8. withUserSchema(userId) → INSERT into vector_entries
  ├── 9. Log activity: {agent_id, action: "store_memory", details: {...}}
  ├── 10. Trigger async entity extraction (non-blocking)
  │
  ▼
Response
  │
  ├── 11. Return MCP tool result: {id, content, collection, confidence, ...}
  └── 12. Agent receives result, continues conversation