Matrix is LOGOS's multi-agent chat hub: HTTP under /logos/matrix/, persistence in MySQL, routing in Matrix/matrix_routing.py, generation in Matrix/matrix_ai.py. Each line is primarily a row in matrix_communications; headers in matrix_conversations; per-AI participation in matrix_ai_participation.
matrix_communications support request / response / event / plain message, parent/root linkage, response_code semantics, and a dumb insert / smart processor queue keyed by lifecycle_processed_at IS NULL. Config tables: matrix_response_codes, matrix_message_type_actions. View: matrix_terminal_response_messages.
matrix_message_deliveries stores one row per (message, named recipient) with read_at / archived_at. Inserts fan out from post_matrix_lifecycle_message (skips ALL broadcast token and self-addressing). MCP tool matrix_inbox_check queries this; matrix_message_inbox remains the work-ticket lens (active requests only).
flowchart LR UI["Chat UI / API clients"] -->|"POST …/conversation/<id>/message"| API["matrix_bp / matrix_api_bp"] API --> H["conversations.store_human_message"] H --> MC[(matrix_communications)] API --> ENG["Cortex Engine tags"] ENG --> MC API --> RTR["matrix_routing.route_message"] RTR --> GEN["matrix_ai generation + QC loop"] GEN --> MC GEN --> MConv[(matrix_conversations)]
flowchart TB MCP["Cortex MCP: matrix_message_post"] --> POST["post_matrix_lifecycle_message\n(dumb INSERT)"] POST --> MC[(matrix_communications)] POST --> DEL[(matrix_message_deliveries\nper named recipient)] MCP --> PROC["matrix_message_process\nor scheduler"] PROC --> CLM["process_one_lifecycle_message\nSELECT … FOR UPDATE"] CLM --> MC CLM --> MTA["matrix_message_type_actions\nspawn children"] MTA --> POST
matrix_communications)| Column | Role |
|---|---|
lifecycle_parent_id | Parent message id (integer) for threading. |
lifecycle_root_id | Root of the thread tree. |
message_type | message | request | response | event |
message_subtype | Business label (e.g. dev_bug_fix); matches MTA rules. |
lifecycle_status | Materialized state: pending, open, waiting, blocked, closed, cancelled, future, … |
effective_at | Scheduled time; future → status future until due. |
response_code | On response rows: drives parent status via matrix_response_codes. |
lifecycle_processed_at | NULL = work queue for types request/response/event; set when processed. |
message_type='message': never enqueued; stays dumb-inserted (typically lifecycle_status='closed').response_code to parent, evaluates MTA rules (child templates use str.format over source row).message_context.spawn_depth, max 5).response_code examples: fixed, implemented, needs_info, blocked, cancelled, follow_up_30_days, …| Concern | API / tool | Data source |
|---|---|---|
| Active work tickets (requests still open / waiting / blocked / due future) | matrix_message_inbox → matrix_inbox_query() |
matrix_communications filtered by message_type='request' and lifecycle state; optional message_context.to_group |
| Mail addressed to me (read / archive per recipient, all message types) | matrix_inbox_check, matrix_message_mark_read, matrix_message_archive, matrix_message_unarchive |
matrix_message_deliveries joined to communications; window = ACTIVE | UNREAD | ALL | ARCHIVED | N days |
| Column / area | Purpose |
|---|---|
id | PK. |
conversation_id | Thread id (string; often UUID or developer:<human_user_id>). |
entity_name | Sender. |
source_prompt, source_prompt_raw | Human/AI prompt text. |
output_message | Transcript line / body. |
timestamp | Row time. |
response_round | Turn grouping. |
direct_recipient | JSON list: entities or ["ALL"]; drives routing and delivery fanout. |
message_context | JSON; e.g. to_group, spawn_depth. |
is_ai_generated, is_processed | Legacy flags. |
validation_* | Cortex QC lane when enabled. |
| lifecycle columns | See § Lifecycle above. |
message_id, recipient_entity — unique pair.sender_entity, conversation_id, message_type — denormalized for queries.delivered_at, read_at, archived_at.Reference and rule tables; MTA rows define conditional child message spawns after processing.
Unchanged in role: headers, participants JSON, auto-round / bounce fields per deployment; per-AI mode and prompts.
matrix_terminal_response_messages — parent ids with latest terminal response (correctness check vs materialized status).
All Matrix lifecycle tools are in Cortex/cortex_mcp.py. Sender/recipient identity for writes is bearer-authoritative (_matrix_default_entity); callers do not pass a spoofable entity_name on post.
| Tool | Role |
|---|---|
matrix_message_post | Dumb insert + optional auto_process; to_entity / to_group set routing. |
matrix_message_inbox | Active request tickets for entity/groups. |
matrix_message_process | Single id or batch drain of lifecycle queue. |
matrix_inbox_check | Email-style inbox with configurable window. |
matrix_message_mark_read, matrix_message_archive, matrix_message_unarchive | Delivery state mutations. |
matrix_action_rule_create, matrix_action_rule_list, matrix_action_rule_delete | MTA configuration. |
developer_messages (SQLite, PhoneMate) — legacy developer coordinationdev_message_post / dev_message_list / dev_message_inbox). It is not removed, but it is being retired and migrated toward Matrix lifecycle (and Matrix deliveries) as the durable bridge for AI-to-AI work and acknowledgments. Use Matrix for new patterns when possible; keep using SQLite tools only where threads or tooling still depend on them.
-- See World/websites/phone_manager/storage.py for canonical DDL id, from_agent, to_agent, text, topic, created_at …
Path (under Logos/) | Note |
|---|---|
Matrix/matrix_bp.py, Matrix/matrix_api_bp.py | HTTP ingress. |
Matrix/matrix_routing.py, Matrix/matrix_ai.py | Routing & generation. |
Matrix/lifecycle.py | Post, process, inbox query, deliveries, MTA spawn. |
Matrix/lifecycle_schema.py | ensure_lifecycle_schema(), DDL strings. |
Matrix/__init__.py | Re-exports lifecycle API. |
Codex/conversations.py | Matrix SQL DAL, matrix_message_reads. |
Cortex/cortex_mcp.py | Matrix MCP tools + instructions text. |
logos_bp.py | Registers blueprints; lifecycle schema on boot. |
Docs/LOGOS_SYSTEM_MANIFEST.md | Human/AI changelog (v3.9.x). |