Architecture

Architecture

Tech Stack

Layer	Technology
Runtime	Cloudflare Workers
Database	Cloudflare D1 (SQLite)
Semantic Index	Cloudflare Vectorize
Embeddings	Cloudflare Workers AI (@cf/baai/bge-base-en-v1.5)
Rate Limiting	Cloudflare KV
Protocol	Model Context Protocol (MCP) over HTTP/SSE
Auth	OAuth 2.0 + PKCE, JWT, PBKDF2-SHA256

Data Flow

MCP Client (Claude, ChatGPT, etc.)
    |
    | POST /mcp (JSON-RPC 2.0)
    | Authorization: Bearer <token>
    v
Cloudflare Worker (memoryvault)
    |
    +-- D1 (SQLite) ---- memories, links, users, sessions
    |
    +-- Vectorize ------- semantic embeddings (768-dim)
    |
    +-- Workers AI ------ embedding generation
    |
    +-- KV -------------- rate limit counters

Module Structure

The codebase is split into 15 focused modules:

Core

Module	Lines	Purpose
index.ts	~210	Worker entry point — fetch() handler, URL routing, CORS/security wrapping
types.ts	~200	All shared TypeScript types and interfaces
constants.ts	~55	Configuration values (TTLs, limits, model names, defaults)

Utilities

Module	Lines	Purpose
utils.ts	~360	Pure helpers: ID generation, cookies, parsing, validation
crypto.ts	~115	PBKDF2 password hashing, JWT sign/verify, HMAC, base64url
cors.ts	~95	CORS headers, origin validation, security headers, CSP

Data Layer

Module	Lines	Purpose
db.ts	~730	D1 queries, schema migrations, memory/link/changelog CRUD
vectorize.ts	~475	Embedding generation, vector sync, semantic search, RRF fusion
scoring.ts	~230	Dynamic confidence/importance computation with explainable components

Auth

Module	Lines	Purpose
auth.ts	~470	Session lifecycle, rate limiting, signup/login/refresh/logout handlers
oauth.ts	~910	OAuth2 + PKCE: client registration, authorize, token exchange, metadata

MCP Tools

Module	Lines	Purpose
tools-schema.ts	~910	40+ tool definitions (name, description, inputSchema), release metadata
tools.ts	~3,550	callTool() dispatcher with all tool handler implementations

Presentation

Module	Lines	Purpose
viewer.ts	~4,090	Web viewer HTML + JavaScript (themes, graph, command palette)
routes.ts	~1,300	MCP handler, API endpoints, HTML landing pages, endpoint guides

Request Lifecycle

1. Entry: index.ts receives the request
2. OPTIONS: Preflight requests return CORS headers immediately
3. Schema: ensureSchema() runs idempotent migrations (cached after first call)
4. Routing: URL path determines handler
5. Auth: Most routes call authenticateRequest() — verifies JWT or legacy token
6. Handler: Route-specific handler processes the request
7. CORS: Response is wrapped with CORS and (for HTML) security headers

Multi-Tenancy

Every data query is scoped by brain_id:

• Each user owns one or more brains
• brain_memberships maps users to brains with roles
• All memory, link, changelog, policy, and snapshot queries filter by brain_id
• Vectorize namespaces use brain_id for vector isolation
• Legacy bearer token maps to a shared legacy-default-brain

Dependencies

Runtime (shipped to Cloudflare):

• @modelcontextprotocol/sdk — MCP protocol types
• zod — schema validation

Dev only:

• typescript — type checking
• wrangler — Cloudflare Workers CLI
• @cloudflare/workers-types — Worker API types