# Agent Memory Store API (FastAPI)

## PURPOSE
Most agents start every conversation from zero, forgetting what users told them and redoing finished work. This project builds a small FastAPI service that models the two stores Databricks Agent Memory ships: a **managed session store** (records each conversation turn by turn) and a **managed memory store** (keeps what is worth knowing about a user — preferences, facts, workflows). A `/pipelines/distill` endpoint stands in for the background memory pipeline that turns sessions into durable memories.

## WHY THIS MATTERS
The video describes agent memory on Agent Bricks as three pieces built on Lakebase: managed sessions, managed memory, and the pipelines that connect them. Databricks research found agents with memory passed **3x as many tasks using 31% fewer tokens**. This service makes those three pieces tangible: sessions are appended turn by turn, the pipeline distills and de-duplicates them, and the next conversation is seeded with what the agent already learned.

## HOW TO BUILD
1. Create the app with FastAPI and Pydantic models: `Session`, `MemoryFact`, `MemoryPipelineConfig`.
2. Bind a session store and a memory store in an app-level registry (the video's "bind a session store and a memory store").
3. Expose `POST /sessions/{user_id}/turns`, `GET /memory/{user_id}`, and `POST /pipelines/distill`.
4. Replace the LLM distillation call with a deterministic stub so the API is runnable offline.

```python
@app.post("/pipelines/distill/{user_id}")
def distill(user_id: str, body: PipelineRun):
    session = SESSION_STORE[user_id]
    new_facts = distill_stub(session)      # deterministic stub, no LLM call
    MEMORY_STORE[user_id] = merge(MEMORY_STORE.get(user_id, []), new_facts)
    return {"sessions_scanned": 1, "facts_written": len(new_facts)}
```

## WHEN TO USE IN PRODUCTION
Use it as the control plane for a memory-enabled agent when you want HTTP-accessible session/memory stores and an auditable distill step. Swap the stub for the real Databricks memory pipeline SDK and point storage at Lakebase. Do **not** use a single-process dict store for multi-instance or high-write production — back it with Lakebase and a queue for pipeline runs.

## HOW IT HELPS STUDENTS
Students learn to separate ephemeral session state from durable user memory, to design merge/de-dup logic, and to expose agent infrastructure as a typed API. They finish with a runnable FastAPI service that mirrors a real Databricks feature rather than a toy.

## STARTER CODE
See `starter/main.py` — FastAPI app with session/memory stores, a deterministic distillation stub, and `# TODO` markers for the real pipeline and Lakebase persistence.
