
# Observability

Enagram exposes a suite of read-only endpoints that let you inspect every layer of your agent's memory. These are available both through the dashboard's **Data** panel and directly via the API.

All observe endpoints are prefixed with `/observe/` and require the same `Authorization: Bearer {instance-key}` header as any other request.

---

## Summary

`GET /observe/summary` returns a snapshot of the current memory state — a count of every item in each layer.

```json
{
  "events": 142,
  "episodes": 18,
  "semantic_facts": 31,
  "identity_signals": 7,
  "procedures": 4,
  "open_conflicts": 1
}
```

| Field | Description |
|-------|-------------|
| `events` | Total raw interaction events ingested |
| `episodes` | Compiled episodic memories — groups of related events |
| `semantic_facts` | Extracted facts about the user with confidence scores |
| `identity_signals` | Durable user characteristics (stable, seasonal, volatile) |
| `procedures` | Learned behaviours with observed success and failure rates |
| `open_conflicts` | Facts that contradict each other and have not yet been resolved |

Use this as a health check for memory accumulation. A new application with no events will show all zeros. If events are ingesting but episodes remain at zero, the episode compiler may not have run yet — it operates asynchronously after ingestion.

---

## Events

`GET /observe/events` returns the raw event log — every interaction event that has been ingested, in reverse chronological order.

Useful query parameters:

| Parameter | Description |
|-----------|-------------|
| `page` | Page number (zero-indexed) |
| `limit` | Results per page (default 100) |
| `session_id` | Filter to a specific session |
| `event_type` | Filter by event type |

Each event includes:

| Field | Description |
|-------|-------------|
| `id` | Unique event identifier |
| `session_id` | The session this event belongs to |
| `event_type` | Type — e.g. `user_message`, `assistant_message`, `outcome` |
| `occurred_at` | Unix timestamp in milliseconds |
| `salience` | Computed salience score (0–1) |
| `stored` | Whether the event passed the commit threshold |
| `compiled` | Whether this event has been included in an episode |
| `outcome` | `positive`, `negative`, `neutral`, or `null` |
| `entities` | Named entities extracted from the payload |
| `payload` | The original event payload |

Events with `stored: false` were processed but did not meet the salience threshold — they are retained in the log but do not influence memory.

---

## Episodes

`GET /observe/episodes` returns compiled episodic memories. An episode is a group of semantically related events from a session, summarised and scored by the compiler.

Each episode includes:

| Field | Description |
|-------|-------------|
| `id` | Unique episode identifier |
| `session_id` | The session the episode was compiled from |
| `summary` | Natural language summary of the episode |
| `salience_score` | Overall importance score for the episode |
| `event_count` | Number of raw events that contributed |
| `outcome` | Net outcome across the episode's events |
| `started_at` / `ended_at` | Temporal bounds of the episode |
| `entities` | Key entities mentioned across the episode |

Episodes are the primary unit from which semantic facts and identity signals are extracted. A high `salience_score` means the episode was rich in signal and is more likely to have influenced long-term memory.

---

## Semantic facts

`GET /observe/facts` returns the semantic fact store — specific claims the pipeline has extracted about the user, with confidence scores.

Each fact includes:

| Field | Description |
|-------|-------------|
| `id` | Unique fact identifier |
| `claim` | Natural language statement — e.g. "User prefers concise answers" |
| `confidence` | Current confidence score (0–1) |
| `entities` | Entities the fact concerns |
| `supporting_episodes` | Episode IDs that contributed to this fact |
| `version` | How many times this fact has been updated |

Confidence increases when a fact is corroborated by new evidence and decreases through decay over time. Facts below a minimum confidence threshold are eventually tombstoned and removed from working memory assembly.

If you see a fact with low confidence that should be high, check whether relevant outcome events are being sent — positive outcomes boost the confidence of facts involved in successful interactions.

---

## Identity signals

`GET /observe/identity` returns durable characteristics extracted about the user. Identity signals differ from facts in that they represent stable, recurring patterns rather than specific claims.

Each signal has a stability tier:

| Tier | Description |
|------|-------------|
| `stable` | Consistently reinforced — included in every working memory context |
| `seasonal` | Periodically active — included when contextually relevant |
| `volatile` | Recently observed, not yet confirmed — included cautiously |

Identity signals are promoted through the tiers as they accumulate reinforcements. A `volatile` signal that is repeatedly corroborated becomes `seasonal`, then `stable`.

These signals form the backbone of personalisation — they ensure the agent always has a baseline understanding of who it is talking to, regardless of how long ago the relevant interactions occurred.

---

## Procedures

`GET /observe/procedures` returns learned procedures — patterns of behaviour the agent has identified as reliably successful or unsuccessful.

Each procedure includes:

| Field | Description |
|-------|-------------|
| `trigger` | Description of the context that activates this procedure |
| `confidence` | Current confidence score |
| `success_count` | Number of times this procedure led to a positive outcome |
| `failure_count` | Number of times it led to a negative outcome |

Procedures are compiled from repeated patterns across episodes. They inform the agent about *how* to behave in specific contexts, not just *what* the user is like. A procedure with a high failure rate is a signal that something the agent does consistently does not work — worth investigating.

---

## Conflicts

Open conflicts appear in the summary as `open_conflicts`. A conflict occurs when two semantic facts directly contradict each other and the pipeline cannot automatically resolve them.

Conflicts are resolved automatically after a configured number of days (see `conflict_auto_resolve_days` in Memory Configuration) based on recency — the more recent fact wins. You can also let them resolve naturally as new evidence accumulates.

A persistently high conflict count usually means the agent is receiving inconsistent signals — for example, outcome events that contradict each other for the same type of interaction. Review your outcome logic if conflicts are not resolving.

---

## Using the Data panel

The **Data** panel in the dashboard provides a visual interface for all of the above:

- **Logs** — paginated event log with filtering by session and event type
- **Analytics** — event volume over time, salience distribution, episode compilation rate
- **Observability** — charts for episode salience, procedure success rates, and fact confidence distribution
- **Visualiser** — interactive graph of the memory structure, showing relationships between episodes, facts, and identity signals
