Core Concepts
Recall Logs
Every retrieval is logged with the candidate set, scores, latency, and the user / session that triggered it. Logs power the dashboard recall-quality charts and the cost attribution view.
What gets logged
| Field | Type | Notes |
|---|---|---|
| id | BIGSERIAL | Log row id |
| org_id | BIGINT | Tenant |
| project_id | VARCHAR | Project scope |
| user_id | BIGINT | Caller |
| session_id | VARCHAR | Recall session, NULL for one-offs |
| query | TEXT | Stored hashed if pii_redact=true |
| k | INT | Requested top-K |
| candidates | JSONB | List of {memory_id, scores} |
| returned_ids | BIGINT[] | Final returned ids |
| computation_tier | VARCHAR | low | medium | high |
| latency_ms | INT | End-to-end |
| cost_units | INT | Billed cost |
| silent | BOOLEAN | True if quota-skipped |
| created_at | TIMESTAMPTZ | — |
Reading logs
BASH
curl https://api.memorysync.io/v1/recall-logs?since=2026-05-01T00:00Z&limit=100 \-H "Authorization: Bearer $MS_USER_TOKEN"
The endpoint paginates with cursor tokens. Filter by session_id to replay an agent run, or by silent=true to find quota-skipped queries that should prompt a plan upgrade.
Dashboard surfaces
- Recall Quality — hit-rate by candidate position; flags queries where rank-1 was clicked < 30% of the time (training signal).
- Cost Attribution — usage attributed per project, per session, per route.
- Drift — how candidate score distribution shifts week-over-week; an early warning that the corpus has moved away from the embedding model.
Retention
Logs follow the org’s audit retention policy (default 90 days, configurable 7–2555). Legal hold prevents purge. PII redaction can be enabled per project so the query field is hashed but candidate ids and scores are kept.