# Agent Memory ROI Dashboard (Streamlit + Plotly)

## PURPOSE
This dashboard visualizes whether agent memory is actually paying off for your own workload. It plots sessions recorded, memories distilled, and tokens billed over time, and contrasts "with memory" against "starting from zero" so teams can see the Databricks-reported effect — **3x tasks passed, 31% fewer tokens** — reproduced (or not) on their own data.

## WHY THIS MATTERS
The video's core pitch is economic: agents without memory "redo work they've already done," while memory-equipped agents start each conversation with what the last one taught them. That benefit is invisible unless you measure it. This project turns the pipeline's logs into a live view of memory growth, duplicate merges, and per-user token savings — the dashboard an on-call engineer would actually open to justify keeping memory enabled.

## HOW TO BUILD
1. Load a session/memory event table with Pandas (columns: `ts, user_id, kind, tokens, mem_warm`).
2. Use `st.sidebar` widgets to filter by date range and by user segment.
3. Build Plotly charts: a time series of tokens billed with vs. without memory, a bar of memory facts by kind (preference/fact/workflow), and a KPI row.
4. Compute savings as `1 - billed/raw` and display it against the 31% baseline.

```python
with_mem = df[df.mem_warm].tokens.sum()
raw = df.tokens.sum()
savings = 1 - with_mem / raw
st.metric("Token reduction", f"{savings:.1%}", delta=f"{(0.31 - savings):+.1%} vs baseline")
fig = px.line(df.groupby("ts").tokens.sum().reset_index(), x="ts", y="tokens",
              title="Tokens per conversation")
st.plotly_chart(fig, use_container_width=True)
```

## WHEN TO USE IN PRODUCTION
Use it as the observability surface for a memory-enabled agent: adoption tracking, cost reviews, and A/B comparisons of pipeline configurations. It is the right place to prove ROI before scaling. Do **not** use it for per-request debugging (it is batch/aggregate) and do not point it at raw PII sessions without masking — aggregate memory counts, not verbatim user text.

## HOW IT HELPS STUDENTS
Students practice Streamlit layout, caching (`@st.cache_data`), Plotly Express charts, and building metrics that map a vendor claim to a measurable KPI. They learn that shipping an agent is as much about demonstrating value as building the pipeline.

## STARTER CODE
See `starter/main.py` — a Streamlit app with a synthetic event generator, sidebar filters, KPI metrics, and two Plotly figures, plus `# TODO` markers for real sink wiring.
