# mehulg/memx architecture

> Architecture diagram of the GitHub repository mehulg/memx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mehulg/memx
- Repository: https://github.com/mehulg/memx

## Overview

#### Purpose and Entry Points
memX is a shared, real-time memory service for multi-agent LLM systems. Agents read/write structured keys over HTTP and receive updates through WebSockets. The backend entrypoint is `main.py`; consumers typically use the Python SDK at `sdk/memx_sdk/client.py`. A separate experimental frontend exists under `frontend/`.

#### API and Request Boundary
`main.py` hosts the FastAPI application and exposes value, schema, and subscription endpoints. Every HTTP and WebSocket request carries an `x-api-key`; the API layer resolves authorization before operating on logical keys. The service applies user-derived namespacing internally, keeping client-facing key names stable.

Grounding: `main.py`, `auth.py`, `validate_api.py`

#### Access Control and Identity
API-key validation first supports centralized Supabase lookup when service credentials are configured; otherwise it uses local development ACL records. Authorization is scope/pattern based, separating permitted reads and writes. Authenticated user identity can prefix stored keys, creating tenant isolation at the storage boundary.

Grounding: `validate_api.py`, `auth.py`, `config/acl.json`

#### Schema-Controlled Memory Writes
Schemas are registered per memory key and enforced before values are committed. This makes shared agent state structured rather than arbitrary JSON, while allowing keys without schemas. Schema changes are themselves observable over the subscription system.

Grounding: `schema.py`, `main.py`, `store.py`

#### Redis State Store
Redis is the authoritative persistence layer for values and schemas. The storage abstraction implements timestamped, last-write-wins value semantics, isolating Redis key layout and serialization from API routes and SDK clients.

Grounding: `store.py`, `redis_client.py`, `schema.py`

#### Real-Time Notification Pipeline
After successful value or schema mutations, the backend publishes events through Redis pub/sub. `pubsub.py` bridges those channels to WebSocket subscribers scoped to a key and event type (`value` or `schema`). This decouples write handling from connected client fan-out and permits multiple API instances to share notification infrastructure.

Grounding: `pubsub.py`, `main.py`, `redis_client.py`

#### Client and Agent Integration
The distributable Python SDK wraps authenticated HTTP set/get/schema operations and WebSocket subscriptions, with a configurable `MEMX_BASE_URL`. Example coordinated agents demonstrate a researcher/synthesizer/critic workflow communicating only via memory keys, with a monitor consuming update events.

Grounding: `sdk/memx_sdk/client.py`, `sdk/memx_sdk/__init__.py`, `examples/plan-coordniate/`

#### Runtime and Deployment
The primary runtime is Python 3.12+ with FastAPI/Uvicorn and Redis 7+. Docker Compose provisions the API plus Redis; `REDIS_URL` can instead target external Redis. Supabase is optional and only material for centralized API-key records. A Next.js frontend and Streamlit script are peripheral user-interface experiments, not part of the core memory path.

Grounding: `Dockerfile`, `docker-compose.yml`, `frontend/memx-frontend/app/page.js`

Main entry points: [`main.py`](https://github.com/mehulg/memx/blob/main/main.py) (FastAPI application), [`validate_api.py`](https://github.com/mehulg/memx/blob/main/validate_api.py) (API-key validation), [`store.py`](https://github.com/mehulg/memx/blob/main/store.py) (Storage abstraction), [`pubsub.py`](https://github.com/mehulg/memx/blob/main/pubsub.py) (Subscription bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients"]
  node_agents(("Coordinated agents<br/>example workflow"))
  node_sdk["Python SDK<br/>client library<br/>[client.py]"]
  node_frontend["Experimental frontend<br/>Next.js UI<br/>[page.js]"]
  node_websocket_subscribers(("WebSocket subscribers<br/>live consumers"))
end

subgraph group_api["Memory API"]
  node_api_app["FastAPI application<br/>HTTP/WebSocket boundary<br/>[main.py]"]
  node_auth["Authorization<br/>identity and scopes<br/>[auth.py]"]
  node_api_key_validation["API-key validation<br/>credential resolver<br/>[validate_api.py]"]
  node_acl["Local ACL records<br/>development access data<br/>[acl.json]"]
  node_schema["Schema enforcement<br/>write validation<br/>[schema.py]"]
end

subgraph group_state["Shared State &amp; Events"]
  node_store["Storage abstraction<br/>last-write-wins store<br/>[store.py]"]
  node_redis_client["Redis client<br/>persistence adapter<br/>[redis_client.py]"]
  node_redis[("Redis<br/>authoritative state and pub/sub")]
  node_pubsub["Subscription bridge<br/>event fan-out<br/>[pubsub.py]"]
end

subgraph group_optional["Optional Services"]
  node_supabase[("Supabase<br/>central API-key records")]
  node_compose{{"Docker Compose runtime<br/>deployment<br/>[docker-compose.yml]"}}
  node_container{{"API container<br/>Python FastAPI/Uvicorn runtime"}}
end

node_agents -->|"uses"| node_sdk
node_sdk -->|"HTTP and WebSocket"| node_api_app
node_frontend -->|"calls"| node_api_app
node_api_app -->|"validates x-api-key"| node_api_key_validation
node_api_key_validation -->|"establishes identity"| node_auth
node_api_key_validation -.->|"development lookup"| node_acl
node_api_key_validation -.->|"configured lookup"| node_supabase
node_auth -->|"authorizes namespaced key access"| node_store
node_api_app -->|"validates writes"| node_schema
node_schema -->|"reads and registers schemas"| node_store
node_api_app -->|"reads and writes values"| node_store
node_store -->|"persists through"| node_redis_client
node_redis_client -->|"value and schema data"| node_redis
node_api_app -->|"publishes successful mutations"| node_pubsub
node_pubsub -->|"pub/sub channels"| node_redis
node_pubsub -->|"value/schema events"| node_websocket_subscribers
node_api_app -->|"subscription sessions"| node_websocket_subscribers
node_compose -->|"runs"| node_container
node_compose -->|"provisions"| node_redis

click node_sdk "https://github.com/mehulg/memx/blob/main/sdk/memx_sdk/client.py"
click node_frontend "https://github.com/mehulg/memx/blob/main/frontend/memx-frontend/app/page.js"
click node_api_app "https://github.com/mehulg/memx/blob/main/main.py"
click node_auth "https://github.com/mehulg/memx/blob/main/auth.py"
click node_api_key_validation "https://github.com/mehulg/memx/blob/main/validate_api.py"
click node_acl "https://github.com/mehulg/memx/blob/main/config/acl.json"
click node_schema "https://github.com/mehulg/memx/blob/main/schema.py"
click node_store "https://github.com/mehulg/memx/blob/main/store.py"
click node_redis_client "https://github.com/mehulg/memx/blob/main/redis_client.py"
click node_pubsub "https://github.com/mehulg/memx/blob/main/pubsub.py"
click node_compose "https://github.com/mehulg/memx/blob/main/docker-compose.yml"
click node_container "https://github.com/mehulg/memx/blob/main/Dockerfile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agents,node_sdk,node_frontend,node_websocket_subscribers toneBlue
class node_api_app,node_auth,node_api_key_validation,node_acl,node_schema toneAmber
class node_store,node_redis_client,node_redis,node_pubsub toneMint
class node_supabase,node_compose,node_container toneRose
```

## Components

### Clients

- **Coordinated agents**: example workflow · Researchers, synthesizers, and critics coordinate through keys.
- [Python SDK](https://github.com/mehulg/memx/blob/main/sdk/memx_sdk/client.py): client library · Authenticated HTTP and WebSocket client. · `sdk/memx_sdk/client.py`
- [Experimental frontend](https://github.com/mehulg/memx/blob/main/frontend/memx-frontend/app/page.js): Next.js UI · Peripheral interface outside the core memory path. · `frontend/memx-frontend/app/page.js`
- **WebSocket subscribers**: live consumers · Receive value and schema updates.

### Memory API

- [FastAPI application](https://github.com/mehulg/memx/blob/main/main.py): HTTP/WebSocket boundary · Serves value, schema, and subscription endpoints. · `main.py`
- [Authorization](https://github.com/mehulg/memx/blob/main/auth.py): identity and scopes · Resolves API keys and read/write key-pattern permissions. · `auth.py`
- [API-key validation](https://github.com/mehulg/memx/blob/main/validate_api.py): credential resolver · Uses Supabase when configured or local ACL records in development. · `validate_api.py`
- [Local ACL records](https://github.com/mehulg/memx/blob/main/config/acl.json): development access data · `config/acl.json`
- [Schema enforcement](https://github.com/mehulg/memx/blob/main/schema.py): write validation · Validates registered per-key schemas before commit. · `schema.py`

### Shared State & Events

- [Storage abstraction](https://github.com/mehulg/memx/blob/main/store.py): last-write-wins store · Applies timestamps, namespacing, serialization, and Redis layout. · `store.py`
- [Redis client](https://github.com/mehulg/memx/blob/main/redis_client.py): persistence adapter · `redis_client.py`
- **Redis**: authoritative state and pub/sub · Persists values and schemas and carries cross-instance events.
- [Subscription bridge](https://github.com/mehulg/memx/blob/main/pubsub.py): event fan-out · Maps Redis events to WebSocket subscribers by key and event type. · `pubsub.py`

### Optional Services

- **Supabase**: central API-key records · Optional centralized credential lookup.
- [Docker Compose runtime](https://github.com/mehulg/memx/blob/main/docker-compose.yml): deployment · Provisions the API and Redis, or permits external Redis. · `docker-compose.yml`
- [API container](https://github.com/mehulg/memx/blob/main/Dockerfile): Python FastAPI/Uvicorn runtime · `Dockerfile`

## Connections

- Coordinated agents → Python SDK: uses
- Python SDK → FastAPI application: HTTP and WebSocket
- Experimental frontend → FastAPI application: calls
- FastAPI application → API-key validation: validates x-api-key
- API-key validation → Authorization: establishes identity
- API-key validation → Local ACL records: development lookup
- API-key validation → Supabase: configured lookup
- Authorization → Storage abstraction: authorizes namespaced key access
- FastAPI application → Schema enforcement: validates writes
- Schema enforcement → Storage abstraction: reads and registers schemas
- FastAPI application → Storage abstraction: reads and writes values
- Storage abstraction → Redis client: persists through
- Redis client → Redis: value and schema data
- FastAPI application → Subscription bridge: publishes successful mutations
- Subscription bridge → Redis: pub/sub channels
- Subscription bridge → WebSocket subscribers: value/schema events
- FastAPI application → WebSocket subscribers: subscription sessions
- Docker Compose runtime → API container: runs
- Docker Compose runtime → Redis: provisions