# IMentorMetricsStore interface

> The IMentorMetricsStore interface of Novior.MentorAgent.Abstractions.Interfaces: Optional persistence/source for the admin token & cost dashboard (roadmap…

- URL: https://docs.mentoragent.net/api/novior-mentoragent-abstractions-interfaces/imentormetricsstore
- Verified with: MentorAgent 1.2.0
- Last updated: 2026-10-27
- Packages: Novior.MentorAgent.Abstractions

Optional persistence/source for the admin token & cost dashboard (roadmap \#9). By default MentorAgent keeps metrics only in RAM (they reset when the process restarts). Register a custom implementation **before**`AddMentorAgent()` to make the dashboard survive restarts or to read aggregated data from an external backend:

```text title="Example"
// Local durability — persist a JSON/DB snapshot; the dashboard keeps reading live RAM,
// seeded from the last save on startup.
builder.Services.AddSingleton<IMentorMetricsStore, FileMetricsStore>();

// External source — the dashboard reads the aggregate the #8 OpenTelemetry export already
// pushed to Prometheus / Azure Monitor (multi-instance, historical).
builder.Services.AddSingleton<IMentorMetricsStore, PrometheusMetricsStore>();

builder.Services.AddMentorAgent(options => { ... });
```

The two scenarios use different halves of this contract, so each implementation overrides only the methods it needs (the others keep their no-op defaults):

- **Local store** (file/DB): implements [`IMentorMetricsStore.LoadForSeedAsync`](https://docs.mentoragent.net/api/novior-mentoragent-abstractions-interfaces/imentormetricsstore#loadforseedasync) (restore totals at startup) and [`IMentorMetricsStore.SaveAsync`](https://docs.mentoragent.net/api/novior-mentoragent-abstractions-interfaces/imentormetricsstore#saveasync) (persist periodically + on shutdown). [`IMentorMetricsStore.QueryAsync`](https://docs.mentoragent.net/api/novior-mentoragent-abstractions-interfaces/imentormetricsstore#queryasync) returns `null` so the dashboard serves the live in-RAM snapshot.
- **External source** (Prometheus/Azure Monitor): implements [`IMentorMetricsStore.QueryAsync`](https://docs.mentoragent.net/api/novior-mentoragent-abstractions-interfaces/imentormetricsstore#queryasync) to query the backend the \#8 export already writes to. [`IMentorMetricsStore.SaveAsync`](https://docs.mentoragent.net/api/novior-mentoragent-abstractions-interfaces/imentormetricsstore#saveasync) is a no-op (OpenTelemetry already exports) and there is nothing to seed.

## Definition

Namespace: `Novior.MentorAgent.Abstractions.Interfaces`. Package: `Novior.MentorAgent.Abstractions`.

`public interface IMentorMetricsStore`

```shell
dotnet add package Novior.MentorAgent.Abstractions
```

## Methods

### `LoadForSeedAsync`

`Task<MentorMetricsSnapshot?> LoadForSeedAsync(CancellationToken ct = default)`

Called once at startup so a durable store can restore the previous totals into the in-RAM counters. Return `null` to start fresh (external sources return `null` — they serve live via [`IMentorMetricsStore.QueryAsync`](https://docs.mentoragent.net/api/novior-mentoragent-abstractions-interfaces/imentormetricsstore#queryasync) instead).

### `QueryAsync`

`Task<MentorMetricsSnapshot?> QueryAsync(CancellationToken ct = default)`

Called on every dashboard/endpoint read. External sources query the backend and return the authoritative (possibly multi-instance, historical) aggregate. Local/null stores return `null`, and the caller serves the live in-RAM snapshot instead.

### `SaveAsync`

`Task SaveAsync(MentorMetricsSnapshot snapshot, CancellationToken ct = default)`

Called periodically and on graceful shutdown with the current snapshot. Durable stores persist it (file/DB); external sources leave the default no-op because \#8 OpenTelemetry already exports.

---

- Previous: [IMentorMetrics interface](https://docs.mentoragent.net/api/novior-mentoragent-abstractions-interfaces/imentormetrics.md)
- Next: [IMentorOrchestrator interface](https://docs.mentoragent.net/api/novior-mentoragent-abstractions-interfaces/imentororchestrator.md)