Architecture overview

In plain terms: Eigen Mesh is one app and one database — the browser, MCP clients, and REST APIs all share the same memory, auth, and search logic.

Eigen Mesh is a single SvelteKit application backed by one PostgreSQL instance with pgvector and Apache AGE extensions. Browser UI, REST, and MCP share the same business logic and tenancy model.

Who this is for

Operators planning or auditing a self-hosted deployment
Integrators who need the system map before wiring MCP or REST clients

System diagram

flowchart TB
  subgraph clients [Clients]
    Browser[Browser UI]
    MCP[MCP clients]
    REST[Custom REST apps]
  end

  subgraph app [Eigen Mesh app]
    Auth[Better Auth sessions]
    Ingest[Ingestion pipeline]
    Search[Hybrid retrieval]
    QA[Answer composition]
    Sleep[Consolidation]
  end

  subgraph data [PostgreSQL]
    PG[(Relational SoR)]
    Vec[pgvector embeddings]
    AGE[Apache AGE graph]
  end

  Browser --> Auth
  MCP --> Auth
  REST --> Auth
  Auth --> Ingest
  Auth --> Search
  Search --> QA
  Ingest --> PG
  Ingest --> Vec
  Ingest --> AGE
  Search --> Vec
  Search --> PG
  Sleep --> PG
  Sleep --> AGE

Domains

Domain	Responsibility
Ingestion	Capture, edit, embed, lexical index, graph sync, activity logging
Client capture queue	Browser IndexedDB queue, offline sync, NDJSON progress
Retrieval	Hybrid search (vector + lexical + precomputed graph links), LLM rerank, in-app QA compose
Auth & tenancy	Better Auth, API keys, RLS via `user_id`, scoped DB role
UI surfaces	Capture, memory (graph/timeline/notes), chat, activity, settings, API keys
Consolidation	Nightly salience, ontology prune, communities

Deployment topology

Service	Role
`eigen-app`	SvelteKit Node adapter, port 3000
`eigen-db`	Postgres 16 + pgvector + AGE, port 5432

Docker Compose in the eigen repository defines both services. Managed and self-hosted run identical product code — only operator and infrastructure differ (Deployment model).

Integration surfaces

Surface	Auth	Use case
MCP `/api/mcp`	Bearer API key	AI assistants (Cursor, Claude) — four thought tools
REST `/api/*`	Session cookie	Browser UI, custom apps
Chat `/api/chat`	Session cookie	Memory assistant with tool loop

Security boundaries

Tenant isolation: Row Level Security on all user data; MCP resolves API key → user_id before queries
Embeddings: Stored in Postgres for search; never returned in MCP, chat, or LLM payloads — Embeddings boundary

Implementation detail

For file-level architecture maps (canonical paths, key symbols, conflict ledger), see the contributor section:

Architecture map L1
Ingestion · Retrieval · Auth & tenancy

Troubleshooting

See Troubleshooting for deployment and integration issues.