System map
How the CognitiveX surfaces connect to the FastAPI backend.
The backend entrypoint is icog/api.py. It builds one FastAPI app, initializes
Postgres, the Cogix pipeline, the LLM router, scheduled workers, and then mounts
all product surfaces through route modules.
Runtime shape
| Layer | Code | Responsibility |
|---|---|---|
| API app | icog/api.py | Lifespan, database pool, Cogix init, CORS, routers, /mcp mount |
| Auth | icog/routes/auth.py, icog/dependencies.py | JWT sessions, refresh cookies, personal API keys, MFA, OAuth, device auth |
| Memory | icog/routes/consciousness.py, icog/routes/memories.py | remember, recall, direct memory browsing, pinning, search, deletion |
| MCP | icog/routes/mcp.py, icog/routes/mcp_oauth.py, cogix/integrations/mcp/* | Streamable HTTP MCP, OAuth + PKCE, tools, read-only resources |
| Developer console | icog/routes/developer.py, icog/routes/auth.py | API keys, request logs, usage, costs, agent and connector overview |
| Agents | icog/routes/agents.py, cogix/integrations/mcp/agent.py | Agent profiles, timelines, context summaries, autonomous MCP tasks |
| Mind graph | icog/routes/mind.py | Graph, relationships, pathing, live recall events, dream status |
| Reflexes | icog/routes/reflexes.py, cogix/reflexes/* | User-defined automations, parsing, execution, costs, vault grants |
Product hosts
api.cognitivx.io is the canonical API origin. The app also allows the product
frontends as CORS origins: icog.app, auth.cognitivx.io,
console.cognitivx.io, developers.cognitivx.io, docs.cognitivx.io,
research.cognitivx.io, and forum.cognitivx.io.
The frontend SDK defaults to cognitivxOrigins.api from @cognitivx/config.
Browser apps rely on a refresh cookie set for the parent domain; API-key
clients use X-API-Key or a bearer token that starts with icog_.
Startup workers
The lifespan hook starts more than the HTTP router:
- a Cogix memory pipeline and LLM router
- cost tracking and task-model registration
- URL extraction and URL snapshot pruning
- identity audit and registry hot-reload jobs
- mood, personality, VAD, and embedding backfill workers
- dream consolidation and cognitive heartbeat loops
- reflex executor wiring behind feature flags
- MCP Streamable HTTP session manager
That means deploy health is not just "FastAPI responded"; check worker logs when recall, dreams, reflexes, or mood/personality surfaces look stale.