> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sovseal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Three-Layer Hybrid Metrics

> How the dashboard monitors activity, quotas, and usage without exposing plaintext data to the server.

Unlike traditional agent memory platforms that parse and aggregate database rows server-side, sovseal operates on a **hybrid metrics model**. Because the replication server is completely blind to your plaintext payloads, metrics are divided into three distinct layers based on where they are computed and what data they expose.

## The Three Layers

| Layer                         | Computed By            | Server Visibility     | Examples                                                                                                                                            |
| :---------------------------- | :--------------------- | :-------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Layer A — Server-Known**    | Replication Server     | ✅ Metadata only       | Encrypted snapshot count, total bytes stored, requests/min, replication latency, active device count, last sync timestamp, and request geolocation. |
| **Layer B — Client-Derived**  | Local Browser / Client | ❌ Never leaves device | Memory count, entity graphs, topic/tag distribution, payload size analysis, lineage tree visualization, and vector similarity index.                |
| **Layer C — Opt-In Reported** | Client (with consent)  | ✅ Aggregated counts   | Total count of memories (no payloads or keys) synchronized for cross-device rollups, and weekly activity digests.                                   |

***

## The Honesty Ledger Rule

To remain transparent about data privacy, the dashboard enforces the **Honesty Ledger Rule**:

> **Every metric shown on the screen must carry a badge indicating its provenance.** If the dashboard cannot verify the source and privacy boundaries of a metric, it is not displayed.

This badge system is represented by three visual **Provenance Chips**:

* `[server]`: Computed purely from metadata. Available even when the database key is not loaded.
* `[local]`: Decrypted and calculated in-memory on the client device. Replaces numbers with a lock icon (`🔒 Load key to decrypt`) if the local key is missing.
* `[synced]`: Voluntarily transmitted to the server in aggregated, anonymized format for project-wide tracking.

***

## KPI Card Mappings

The standard KPI cards are mapped according to their provenance layers:

### Total Memories `[local / synced]`

* **Unauthenticated**: Displays `🔒` with a prompt to load the decryption key.
* **Authenticated**: Decrypts records in the browser, counts active (non-tombstone) paths, and displays the local total.
* **With Sync Consent**: Displays the latest aggregated count reported to the server (Layer C), allowing multi-device tracking without key presence.

### Sync Ops Quota `[server]`

* Tracks total write and sync operations against your account limits. Computed purely from API requests on the server (Layer A), ensuring billing matches usage without exposing content.

### Retrieval Events `[server]`

* Represents the total volume of `recall_memory` operations requesting remote validation or pulling snapshot updates. The server counts the requests but remains blind to query content or returned results.

### Store Ops `[server]`

* Displays the volume of incoming write-behind updates. Used to measure write throughput and outbox sync performance.

***

## Multi-Device & Project Isolation

When swapping projects or logging in from multiple devices:

* **Project Switch**: Choosing a different project in the dashboard scopes all Layer-A metrics to the new project ID and prompts you for that project's encryption key. Layer-B stats are flushed from browser memory and reloaded from the new project's local storage index.
* **Device Sync**: Adding a new device registers it as an active node under Layer A. The device pulls ciphertext snapshots, decrypts them locally, and populates its local Layer-B explorer. The server remains blind throughout the setup process.