mehulg/memx

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