🇬🇧 English · 🇷🇺 Русский

vesma-vitals

Methodology and instrumentation for honest measurement of the Vesma memory server. Prove — or honestly refute — every promise: dynamic context, the right memory per request, token savings, the health of every subsystem.

Navigation · What it is · Why a separate project · Architecture · Documentation · Status

What it is

The Vesma owner framed the problem (2026-09-09): "in words and in docs everything looks great, but in practice there is no feeling that the context is REALLY composed dynamically. How many tokens do we actually save? Does the right instruction or a piece of memory get substituted on request?" The server stands (S1–S4) measure output quality and latency — none answers what memory gives the loop or whether every function actually works.

vesma-vitals closes this gap with two circuits:

Both decisions were made by the Vesma Architectural Committee (2026-09-09, mnemos record 7ec9dda3 core + 061398fe addendum "full functionality"); ADR-0026 is the formal record. This repository is the implementation.

Why a separate project

• Trust boundary: the metrics collector is a guest in the server. Code isolation rules out accidental coupling of telemetry with the assemble_context pipeline and the main store.
• Embedding contract: vesma-vitals embeds into vesma at a minimal set of points (10 defined boundaries); the server does not depend on it.
• Speed: its own CI, its own releases, its own review cycle — metrics do not wait for the server's release window.
• Reusability: the methodology applies to any memory server with the same contract shape (harness → memory → model).

Navigation

Architecture

flowchart LR
    subgraph VESMA["Vesma server (unchanged)"]
        AC[assemble_context and others]
        EP[10 boundaries: MCP / REST / background / CLI]
    end
    subgraph VITALS["vesma-vitals"]
        SINK["MetricsSink<br/>allowlist, fail-closed"]
        LEDGER[("metrics.sqlite sidecar<br/>5 born-final tables")]
        S5["S5 memory-value stand<br/>two arms on/off"]
        EXP["Prometheus hybrid<br/>counters + p50/p95 from rollup"]
        REPORT["Report: F8/F9 traffic light<br/>PASS / FAIL / NO-DATA"]
    end
    EP -->|verb, status, latency, project| SINK
    SINK --> LEDGER
    LEDGER --> EXP
    LEDGER --> S5
    S5 --> REPORT
    EXP --> REPORT

Key properties: allowlist schema with no columns for raw text (privacy by structure, not by filtering), keyed-HMAC fingerprints, born no-federate, TTL 30/90 days fail-loud, status taxonomy — invariant / corridor / verdict.

Documentation

Status

Foundation laid (2026-09-09); phase A in progress. The passive-collection library core is ready (born-final schema + C1 canary + MetricsStore); vesma integration is a separate PR in the server repo. Full status — docs/status.md. Promises and their measured status — docs/claims.md.

Critical actions

Any action touching the main vesma store is performed only by vesma's own means — vesma-vitals has no write API into it.

Licensing is the owner's decision; the project inherits the canon of the Vesma ecosystem (vesma — the server, vesma-eyes — the web viewer).