# Technical Architecture The architecture of Cerebros is the bridge between vision and reality. To transform large language model–driven agents into cognitive companions, Cerebros must be more than an idea: they must be concrete, reproducible, and operational. This is achieved by grounding them in four foundational layers — **Graphiti SDK, ADK Runner, MCP interoperability, and the surrounding API and UI ecosystem**. *** ### Graphiti SDK: The Knowledge Engine At the heart of every Cerebro lies a **temporal knowledge graph**. Concepts and relationships are not stored as loose embeddings or ad hoc memories, but as structured nodes and edges enriched with timestamps, provenance, and decay policies. This ensures that knowledge is both persistent and adaptive: it remembers when information was observed, how it evolves, and when it begins to lose relevance. The **Graphiti SDK** provides the machinery to ingest, query, and maintain this graph. It connects directly to graph backends such as Neo4j and manages the full lifecycle of knowledge: * **Ingestion** — transforming raw sources (documents, data streams, annotations) into normalized graph entities and relations. * **Retrieval** — supporting hybrid queries that combine temporal constraints, semantic similarity, and graph traversal. * **Context blocks** — packaging facts and citations into explainable units that agents can use directly. By serving as the memory substrate, the Graphiti SDK ensures that every Cerebro is grounded in structure, persistence, and provenance. *** ### ADK Runner: The Agent Interface While the graph engine provides knowledge, it is the **agent runtime** that gives it purpose. The **ADK Runner** acts as the planner and executor that integrates Cerebros into agent workflows. When an agent receives a prompt, the ADK Runner determines the appropriate queries, retrieves relevant subgraphs or context blocks, and composes them into a response enriched with citations. It enforces tool policies, tracks reasoning steps, and ensures traceability across the entire interaction. This layer bridges **natural language intent** with **graph-based memory**, turning static data into dynamic reasoning. It allows agents to not only recall information but to respect prerequisites, adapt retrieval windows, and surface explanations alongside answers. *** ### MCP Layer: The “USB-C” for Brains For Cerebros to succeed, they must be **portable and interoperable**. Agents, IDEs, and orchestration frameworks should be able to plug in a Cerebro as easily as plugging a device into a USB port. This is the role of the **Model Context Protocol (MCP)**. Through MCP, each Cerebro exposes its capabilities as JSON Schema–defined tools — such as `graph.query_subgraph`, `graph.context_block`, and `graph.add_episode`. Any agent that understands MCP can discover these tools, invoke them, and receive structured outputs without requiring bespoke SDKs. This universality allows Cerebros to operate across environments: * As standalone modules connected to agents. * As interoperable services discoverable by IDEs and orchestrators. * As nodes in larger ecosystems where multiple brains collaborate. The MCP layer makes Cerebros truly composable, enabling them to be reused and combined across domains and applications. *** ### API and Service Layer: Management and Orchestration Beyond the core, Cerebros provide a service layer that makes them usable in practice. The **FastAPI-based backend** exposes endpoints for creating, ingesting, exporting, and running Cerebros. This includes operations such as: * Uploading new sources for ingestion. * Querying or snapshotting a graph. * Executing an agent run with a given Cerebro. * Importing or exporting `.cerebro` packages. * Accessing a marketplace of shared brains. By centralizing management, this layer enables administrators, developers, and end users to interact with Cerebros without needing to handle the underlying graph directly. It also establishes the foundation for marketplaces and collaborative distribution. *** ### Frontend and Marketplace: Usability and Sharing To move from infrastructure to adoption, Cerebros must be approachable. The **Svelte-based frontend** provides a user-friendly interface that allows: * **Building and editing** brains from raw sources. * **Visualizing graphs** as timelines and k-hop neighborhoods. * **Chatting with brains**, where every answer shows its provenance. * **Exploring a marketplace**, where Cerebros can be published, installed, and rated. This combination of usability and discoverability ensures that Cerebros are not confined to researchers or engineers. Educators, students, enterprises, and communities can create, share, and refine brains — turning the architecture into a living ecosystem. *** ### Packaging, Validation, and Portability Every Cerebro is distributed as a portable `.cerebro` package. Inside it are: * `manifest.yaml` — the canonical descriptor with metadata, retrieval policies, and compatibility requirements. * Schemas for entities and relations. * Pipelines for ingestion. * Snapshots of the graph. * Checksums and optional signatures for integrity. This packaging guarantees reproducibility and security. A Cerebro created in one environment can be validated, signed, and imported into another with confidence that its structure and provenance remain intact. *** ### Observability, Security, and Scalability Finally, the architecture embeds operational robustness. Every Cerebro service provides health checks and metrics; logs include trace identifiers for auditability; and CI/CD pipelines enforce linting, schema validation, and automated testing. Security is enforced through scoped tokens, strict package validation, provenance-first retrieval, and privacy controls. Scalability is achieved through sharding, caching, and queue-based ingestion pipelines, ensuring that Cerebros can grow with demand. *** ### A Blueprint for Cognitive Infrastructure Together, these layers form the **technical backbone of Cerebros**. The Graphiti SDK grounds knowledge in structure and time, the ADK Runner connects it to agent reasoning, the MCP layer makes it universally interoperable, and the APIs, frontends, and marketplaces make it usable and shareable. This architecture is not speculative: it is actionable. It provides a blueprint for building the first generation of Cerebros — modular brains that transform agents from fluent assistants into adaptive, explainable companions. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://cerebros.gitbook.io/cerebros/technical-architecture.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.