# Agent Memory Pipeline Simulator (SimPy + NumPy)

## PURPOSE
This discrete-event simulation models the background memory pipeline described in the Databricks video: conversations arrive, sessions are recorded turn by turn, and a pipeline "distills sessions into memory, merges duplicates, and keeps memory files easy to access." The simulator answers a design question students will face on real systems: how much does memory reuse cut token cost, and how far behind can the background pipeline fall under load?

## WHY THIS MATTERS
The video's headline finding — agents with memory "passed three times as many tasks, using 31% fewer tokens" — is a systems claim, not just a model claim. It only holds if the pipeline keeps up and memories are ready before the next conversation starts. By simulating arrival rates, distillation service time, and merge/dedup work, students see why the "background synthesis" Databricks automates matters: a lagging pipeline means agents reload redundant context and the savings evaporate.

## HOW TO BUILD
1. Use SimPy `Environment` with a `Resource` for the memory pipeline (limited distill workers).
2. Generate conversations with NumPy from a Poisson process; each session carries a token count.
3. On session end, request a pipeline distill job; apply a 31% token reduction when a user's memory is already warm.
4. Merge/duplicate work is modeled as extra service time; collect stats and print a summary.

```python
distill = simpy.Resource(env, capacity=2)

def session(env, user, tokens):
    yield env.timeout(sample_turn_time())
    with distill.request() as req:
        yield req
        yield env.timeout(distill_service_time(tokens))   # background synthesis
        warm_memory.add(user)                              # next convo starts smarter
        stats["tokens"] += tokens * (0.69 if user in warm_memory else 1.0)
```

## WHEN TO USE IN PRODUCTION
Use it to size pipeline workers, choose session-eviction policy, or set SLAs on "memory ready before next conversation." Great for capacity-planning and cost justifications before you commit to a deployment. Do **not** use it as a correctness test for your extractor — it models timing and cost, not extraction quality, and its arrival assumptions should be replaced by your real telemetry.

## HOW IT HELPS STUDENTS
Students learn SimPy resources/queues, NumPy sampling, and how to translate a marketing statistic (31% fewer tokens) into a causal model with tunable knobs. They walk away understanding that agent memory is a throughput problem as much as a modeling one.

## STARTER CODE
See `starter/main.py` — a SimPy simulation with a pipeline `Resource`, NumPy-driven arrivals, warm-memory token savings, and `# TODO` markers for realistic service-time distributions.
