Observability

Overview

Observability on sovseal respects the zero-trust data boundary. The Edge servers measure request flows and resource allocations solely at Layer A (unencrypted metadata). This design allows you to monitor sync operations and storage sizes without compromising cryptographic confidentiality.

Per-Project Metrics

The sovseal Dashboard visualizes operational health metrics:

Replication Lag: Time delta between local client commit and remote Edge receipt.
Ciphertext Bytes Stored: Total volume of encrypted payloads residing in the storage bucket.
Operation Counts: Total number of store_memory (write), recall_memory (read), and check_in requests.
Sync Devices: Number of concurrent devices actively replication-synced.

All metrics are compiled from metadata tables (usage_counters) and never traverse decryption blocks.

Webhooks

Wired to real-time events, sovseal webhooks trigger callbacks in your backend when memories are updated.

[!IMPORTANT] Zero-Knowledge Webhook Security Invariant Webhook payloads carry only metadata and client-side payload hashes. Plaintext memory values are never transmitted in webhook bodies to prevent leakage to external servers.

Supported Events

memory.add: Triggered when a new encrypted snapshot is replication-synced.
memory.delete: Triggered when a memory block is deleted.
quota.limit_reached: Triggered when a tier-limit is hit.

Webhook Payload Example (`memory.add`)

{
  "event": "memory.add",
  "project_id": "proj_8f7e6d...",
  "agent_id": "9f8e7d... (sha256 hash of project+key)",
  "sequence_number": 42,
  "client_payload_hash": "a1b2c3d4e5f6... (VSR anchor)",
  "timestamp": "2026-06-10T11:22:37Z",
  "ciphertext_size_bytes": 1284
}

Tamper-Evident Audit Log

Every privileged team action — granting or revoking key access, rotating a DEK, adding or removing a member, writing shared memory — is appended to a per-team, append-only ledger. Each entry commits to the one before it with a SHA-256 hash chain:

entry_hash = SHA-256( seq | org_id | actor | action | resource_type
                      | resource_id | metadata | prev_hash )

The first entry's prev_hash is 64 zeros (genesis); every subsequent entry's prev_hash is the previous entry's entry_hash. Because each link commits to all prior history, any retroactive edit, deletion, or reorder breaks the chain — and verification reports the exact sequence number where it broke.

UPDATE and DELETE on the ledger are rejected at the database level, so the trail cannot be rewritten in place even with direct table access.

Zero-knowledge boundary

Audit entries carry only non-secret descriptors — member ids, roles, sequence/epoch numbers, byte sizes, and rotation reasons. They never contain a cleartext or wrapped DEK, a private key, or any plaintext/ciphertext memory. The audit log strengthens compliance without weakening the zero-knowledge guarantee.

Verify & export from the dashboard

The Audit Log page in the dashboard lets administrators:

View the ledger, filtered by actor, action, or date range.
Verify Chain Integrity — a one-click end-to-end check that returns valid or the exact broken_seq and reason (entry_hash_mismatch for an in-place edit, prev_hash_mismatch for a deletion/reorder).
Export the full ledger as JSON or CSV. The JSON export embeds the verification result so a downstream auditor can trust it without re-querying the server.
Export Format: JSON (with embedded chain verification) or CSV.
Scoping: Filter by actor, action type, or created-at date range.
Compliance: Cryptographic evidence for SOC 2, HIPAA, or internal review.

Telemetry Opt-Out

The SDK gathers telemetry data by default (only aggregate counts of operation successes/failures and library version numbers). No payload contents, keys, or user identifiers are ever sent.

Disabling Telemetry

To disable telemetry completely in the SDK or MCP server, set the environment variable:

export SOVSEAL_TELEMETRY_OPTOUT=true

Alternatively, configure the setting in ~/.sovseal/config.json:

{
  "project_id": "...",
  "api_key": "...",
  "telemetry": false
}

On this page