# Architecture

Zaxy has four primary layers: Eventloom, extraction, projection backends, and MCP. Each layer has a narrow responsibility so the system remains replayable and auditable. Eventloom stores append-only JSONL events with hash-chain integrity. The extraction engine converts typed events into `ExtractedEntity` and `ExtractedEdge` objects. Projection backends store temporal graph views for retrieval, dashboard inspection, and graph traversal. MCP exposes the memory operations to agent frameworks and clients.

The data flow starts when an agent calls `memory_append`, a Python caller uses `MemoryFabric.append`, a service calls `MemoryFabric.ingest_documents` for local project material, or `MemoryFabric.ingest_transcript` imports sanitized session turns. Zaxy validates the payload, writes an Eventloom event, runs extraction, optionally generates embeddings, upserts graph facts, emits metrics, and traces the operation through Pathlight when enabled. Query calls flow in the opposite direction: input validation, optional query embedding, exact search, keyword search, vector similarity, traversal expansion, fusion, and compact context chunk rendering.

Context lifecycle APIs sit above replay and retrieval. `MemoryFabric.assemble_context` replays recent session events, queries ranked graph memory, reserves a small verbatim Eventloom source-recall lane, projects a bounded active memory working set, and formats the result into a prompt-ready bundle. `after_turn` appends the completed turn and returns bounded context for the next turn. `handoff_bundle` packages summary, replay, integrity status, and retrieval into a portable resume object. `cleanup_subagent` finalizes a subagent session with a cleanup event and emits a handoff bundle. These APIs use Eventloom as the recovery anchor, the graph as the relevance layer, verbatim retrieval as the exact-source lane, and the working set as the model-facing memory projection instead of creating a separate context cache.

Eventloom is deliberately the bottom layer. It must remain useful even if a projection backend is unavailable or a projection bug is discovered. If a graph needs to be rebuilt, replay the log and re-run extraction. This is the reason Zaxy does not silently overwrite facts: graph entities carry `valid_from` and `valid_to` windows, and reasserted facts become new versions.

The embedded LadybugDB projection is the default graph backend because it preserves graph-native traversal, citations, temporal versioning, and replay without a separate graph service. LadybugDB is the actively maintained fork of the archived Kuzu engine; Zaxy 2.3 moved the embedded store to it (exact-pinned) after verifying the fork against Zaxy's own defect reproductions and scale lanes. Neo4j remains the quality and performance control backend, and pgGraph remains an experimental Postgres-native projection backend. See zero-friction-runtime-roadmap.md for the embedded runtime gates and backend lifecycle.

Zaxy does not delegate schema control to a high-level graph-memory abstraction because temporal validity, invalidation semantics, index management, and query fusion need to be explicit and testable. The graph schema is documented in graph-schema.md.

Pathlight is observability, not storage. It records memory operation traces so operators can see append/query/replay/invalidate spans and correlate them with agent runs. Zaxy can run without Pathlight; missing tracing must not prevent memory operations.

The remote interface is MCP over stdio or SSE. Stdio is best for local desktop and framework integrations. SSE is best for daemon mode, but it requires bearer auth and per-client session scoping in production. See mcp.md and security.md for those contracts.

The public site at site/index.html describes the system for new users. The README.md gives a quick start. The runbook at runbook.md covers operations and incident response.