Architecture

Zaxy has four primary layers: Eventloom, extraction, Neo4j, 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. Neo4j stores temporal graph projections. 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 Neo4j is unavailable or a projection bug is discovered. If the 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.

Neo4j is used directly through the official driver. 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.