Skip to content

09_runtime_contract.md

Latest commit

 

History

History
226 lines (158 loc) · 7.59 KB

09_runtime_contract.md

File metadata and controls

226 lines (158 loc) · 7.59 KB
Raw

RUNTIME CONTRACT & OBSERVABILITY

Environment Variables, C4 Architecture, and Dashboards

Foundational Engineering Specification (Document 09 of 12)

Namespace: memory-steward • Owner: architecture-team

Navigation

← Prev: Document 08 (Verification) | Next: Document 10 (Landscape) →

0. Status, Scope, and Authority

Status: FOUNDATIONAL Audience: Core maintainers, operators Change policy:

  • Append-only
  • No silent edits

Back to top

1. Purpose

This document defines the Physical Architecture and Runtime Configuration of the system. It replaces ad-hoc READMEs with a strict contract.

Back to top

2. System Architecture (C4 Model)

graph TD
    User((User))

    subgraph "Memory Steward System"
        UI[Open WebUI]
        Router[<b>Memory Router</b><br>Orchestrator]
        Steward[<b>Memory Steward</b><br>Admission Controller]
        Builder[<b>Builder LLM</b><br>vLLM / Inference]

        subgraph "Storage"
            DB[(Postgres<br>Canonical)]
            Vector[(Qdrant<br>Index)]
            Logs[(Log Sink<br>PVC)]
        end
    end

    User -->|Chat| UI
    UI -->|OpenAI Protocol| Router
    Router -->|Inference| Builder
    Router -->|Read Static| DB
    Router -->|Search| Vector

    Router -.->|Async Admit| Steward
    Steward -->|Write Dynamic| DB
    Steward -->|Upsert| Vector

    Router -.->|Logs| Logs
    Steward -.->|Logs| Logs
Loading

Back to top

3. Request Lifecycle (Sequence)

sequenceDiagram
    participant U as User
    participant R as Router
    participant Q as Qdrant
    participant B as Builder
    participant S as Steward

    U->>R: POST /chat/completions
    par Retrieval
        R->>Q: Search (Project ID)
        R->>R: Load Static Rules
    end
    R->>R: Assemble Context
    R->>B: Generate(Prompt)
    B-->>R: Response
    R-->>U: Response

    rect rgb(240, 240, 240)
        Note right of R: Async Admission
        R->>S: Admit(User + Assistant Msg)
        S->>S: Extract Fragments
        S->>Q: Upsert Vector
    end
Loading

Back to top

4. Environment Variable Contract

4.1 Memory Router

Variable Default Description
POSTGRES_DSN Required Canonical storage connection.
QDRANT_URL http://qdrant:6333 Vector store endpoint.
BUILDER_BASE_URL Required vLLM / OpenAI inference endpoint.
STEWARD_URL Required Async admission endpoint.
MAX_CONTEXT_TOKENS 2000 Safety cap for injection.
OPEN_WEBUI_URL http://open-webui:8080 Open WebUI base URL for slash-command seeding.
OPEN_WEBUI_API_KEY Optional Open WebUI API key. Required for /glap slash-command auto-seeding. Set via open-webui-api-key secret.

4.2 Memory Steward

Variable Default Description
MIN_CONFIDENCE 0.7 Threshold for memory persistence.
EMBEDDINGS_URL Required Service for vectorization.

4.3 Log Aggregator (Vector) [New]

Variable Default Description
LOG_DIR /var/log/memory_steward_logs Root directory for persisted logs.
LOG_ROTATE_MAX_SIZE_MB 10 Size threshold for rotation.
LOG_ROTATE_MAX_FILES 10 Max rotated files per log.
LOG_RETENTION_DAYS 14 Age horizon for purge.
LOG_TOTAL_CAP_MB 5120 Global cap for all logs under LOG_DIR.

4.4 MCP Diagnostics [New]

Variable Default Description
MCP_MAX_LINES 1000 Hard cap for logs.read.
MCP_MAX_WINDOW_MINUTES 360 Hard cap for smart_search time window.
MCP_RESPONSE_MAX_BYTES 524288 Response size ceiling (bytes).

Back to top

5. Dashboard Specification

Dashboards are powered by the Diagnostics Plane (Postgres telemetry schema).

5.1 Grafana Views (Canonical)

  1. Router Overview: RPS, Error Rate, Latency (p95).
  2. Steward Health: Admission Lag, Fragments Inserted per Minute.
  3. Retrieval Quality: “Zero Candidate” rate (Blind spots).

5.2 Verification

-- Check if telemetry is flowing
SELECT count(*) FROM telemetry.request WHERE created_at > now() - interval '1 hour';

Back to top

7. Log Aggregation Component (Vector)

Component name: vector-agent (DaemonSet)

Purpose: Harvest all container logs, persist to PVC, enforce rotation and retention, and expose bounded diagnostics via MCP.

Contracts

  • Directories
    • LOG_DIR (default /var/log/memory_steward_logs)
  • Rotation / Retention
    • LOG_ROTATE_MAX_SIZE_MB (default 10)
    • LOG_ROTATE_MAX_FILES (default 10)
    • LOG_RETENTION_DAYS (default 14)
    • LOG_TOTAL_CAP_MB (default 5120)
  • Time
    • LOG_TZ (default cluster timezone) for timestamp normalization

Kubernetes Resources

  • DaemonSet: vector-agent
  • ConfigMap: vector-config (immutable pipeline and retention rules)
  • PVC: vector-logs (ReadWriteOnce) mounted at LOG_DIR
  • ServiceAccount: vector-agent (read pod metadata only)

Back to top

8. Closing Statement

This runtime contract ensures that deployment is deterministic. If the Env Vars match, the C4 architecture holds true.

Amendment 09.1: Open WebUI Frontend

Date: 2026 Scope: Sections 2, 3, 4.1

The frontend component has been replaced from AnythingLLM to Open WebUI. All references to AnythingLLM / UI in the C4 diagram and sequence diagram now refer to Open WebUI. Two new environment variables have been added to the Memory Router contract (OPEN_WEBUI_URL, OPEN_WEBUI_API_KEY) to support lazy slash-command seeding via mcp_bridge.py. The open-webui service is added to the log aggregation file layout (see Doc 06 Section 11.2).

END OF DOCUMENT 09