Architecture

One-Sentence Summary

Myria is a PostgreSQL-backed memory service that turns an append-only event log into participant-scoped semantic snapshots and exposes the result through a stdio MCP server.

System Boundary

Myria is responsible for:

• accepting canonical events
• storing raw history
• building and serving TopicIndex snapshots
• preserving provenance from summaries back to events
• exposing both normal conversation tools and admin/observability tools

Myria is not responsible for:

• frontend transport handling
• general agent orchestration
• account mapping across channels
• the application’s main reasoning loop

Core Runtime Shape

Myria has three persistent layers:

• event log The immutable source of truth.
• active snapshot The current read-only semantic index used by live queries.
• staging snapshot The next candidate snapshot built in the background and published atomically.

Main Subsystems

Ingest

Accepts canonical events, enforces idempotency when a dedupe key is present, generates event_id, and appends the event to PostgreSQL.

Query

Serves two main read paths:

• query_event_nodes Direct raw-event retrieval.
• query_references Snapshot walk plus fresh-tail retrieval, assembled into one rooted tree.

Builder

Builds a new snapshot from the old cutoff to a new cutoff. The builder is globally triggered and processes events by exact participant set.

Snapshot Registry

Tracks which snapshot is active and ensures publish remains atomic and serialized.

Internal LLM Orchestration

Runs the builder and tree-walker LLM workflows behind deterministic Go control. The LLM never talks to PostgreSQL directly. It only sees bounded, participant-masked tool results.

Request Flow

Write Path

append_event:

1. validate input
2. normalize participants
3. dedupe on (channel, source_event_key) when present
4. generate event_id
5. append to events
6. update trigger state

Read Path

query_event_nodes:

1. filter raw events by participants and query fields
2. return a rooted tree of event nodes

query_references:

1. pin the active snapshot
2. inspect visible snapshot roots
3. read fresh events after the snapshot cutoff
4. either walk with the internal LLM or fall back deterministically
5. return one rooted multi-child tree

Build Path

1. wait for a build trigger
2. capture the current event-log high-water mark
3. load events since the previous cutoff
4. partition by exact participant set
5. build leaves and internal nodes
6. validate the new snapshot
7. publish atomically

Concurrency Model

• event ingestion is concurrent and idempotent
• build publish is serialized
• active reads are snapshot-stable
• staging writes never change the snapshot pinned by an in-flight query

Transport

Myria v1 exposes MCP over stdio only. There is no network transport in the current implementation.