# Session Distillation CLI (Click + Pandas)

## PURPOSE
This command-line tool reads exported agent session logs (one conversation turn per row) and produces a tidy memory file: the durable facts, preferences and workflows worth keeping about each user. It also quantifies the payoff the Databricks video cites — fewer tokens per task when the agent reuses memory instead of rediscovering context every time.

## WHY THIS MATTERS
The video says agents "start every conversation from zero," forgetting users and redoing work. Databricks built agent memory into Agent Bricks with managed sessions, managed memory, and pipelines that "distill sessions into memory, merge duplicates, and keep memory files easy to access." This CLI is that distillation step in local, inspectable form. The Databricks research team found memory-equipped agents passed **3x as many tasks using 31% fewer tokens** — the `report` command computes your own token-savings ratio from the logs so students can see the claim on real numbers.

## HOW TO BUILD
1. Use Click for three subcommands: `ingest`, `distill`, `report`.
2. Load sessions with Pandas (`pd.read_csv`), group by `user_id`, and sort by turn order.
3. Extract candidate memories with a deterministic rule-based pass (no LLM required).
4. Write a clean parquet/CSV "memory file" per user and print a savings summary.

```python
@click.command()
@click.option("--sessions", type=click.Path(exists=True), required=True)
@click.option("--out", type=click.Path(), default="memory.parquet")
def distill(sessions, out):
    df = pd.read_csv(sessions)
    mem = (df.groupby("user_id", group_keys=False)
             .apply(extract_facts))          # deterministic extraction
    mem.to_parquet(out, index=False)
    click.echo(f"wrote {len(mem)} memory rows -> {out}")
```

## WHEN TO USE IN PRODUCTION
Use it for offline batch distillation of session exports, daily cost/token audits, or backfilling memory for a migration. It is ideal in CI to regression-test that your extraction rules still find the same facts. Do **not** use it for real-time synthesis inside a live agent loop — that belongs to the Databricks background memory pipeline; this tool is for batch and analysis.

## HOW IT HELPS STUDENTS
Students practice Click command design, Pandas groupby/apply, deterministic text extraction, and turning a vendor metric (31% fewer tokens) into a measurement they can reproduce. It teaches the sessions-vs-memory distinction concretely and produces an auditable artifact.

## STARTER CODE
See `starter/main.py` — a Click CLI with `ingest`, `distill` and `report` commands, Pandas ETL, a rule-based extraction stub, and `# TODO` markers for custom extractors.
