# Q1 — Design a Memory Module for the Cumin Agent

⏱ **Budget: ~15 minutes** · Weight: 30%

## Context

We build agents like **Cumin** — the AI agent that runs inside a compute sandbox. Today Cumin's runtime looks like this:

| Primitive | Purpose |
|---|---|
| **Containers** | Persistent Linux shells for private work (data processing, analysis, conversion). They stay alive for a conversation. |
| **Functions** | Serverless HTTP endpoints for public things (APIs, dashboards, websites). |
| **Workspace (object store)** | Flat file storage — every file Cumin produces lives here. |
| **Skills** | Markdown files Cumin reads to remember *how* to do tasks (its current, rudimentary long-term memory). |
| **Secrets** | Key/value pairs for credentials/tokens. |

**The gap:** Cumin has no real memory. Between turns it has to re-read its workspace files and skills from scratch. It forgets past conversations, past decisions, and past failures. There is no way to recall *"what did I learn last time I did this?"*

## Your task

Design a **memory module** for Cumin. Be concrete — we want to see storage choices, retrieval logic, and pseudocode, not hand-waving. Cover:

1. **Memory taxonomy** — define at least: *working* (short-term), *episodic* (past tasks/conversations), *semantic* (facts & patterns), and *procedural* (how-to, i.e. the evolution of "skills"). For each: what it stores, an example, expected size, and retention/TTL.
2. **Storage backends** — map each memory type to a concrete store. Where possible, map to **Ghaymah** products (vector store + embeddings, managed PostgreSQL, object storage).
3. **Write policy** — when does the agent write to memory, and what does it write?
4. **Read / retrieval policy** — how does the agent decide what to recall, and with what ranking (e.g. recency + semantic similarity + metadata filters)?
5. **Memory API** — pseudocode for `save`, `recall`, `search`, and (optionally) `summarize`/`forget`.
6. **Agent-loop integration** — pseudocode showing where memory is read/written during a normal turn.
7. **Failure modes & mitigations** — memory poisoning, staleness, context overflow, leakage between users, etc.

## Deliverable

Fill in the template below. Pseudocode blocks should be runnable-in-spirit (correct Python-ish, not perfect).

---

## ANSWER — Cumin Memory Module

### 1. Memory taxonomy

| Type | What it stores | Example | Approx. size | Retention / TTL |
|---|---|---|---|---|
| Working | | | | |
| Episodic | | | | |
| Semantic | | | | |
| Procedural | | | | |

### 2. Storage backends (map to Ghaymah where possible)

| Memory type | Backend | Ghaymah product | Why this choice |
|---|---|---|---|
| Working | | | |
| Episodic | | | |
| Semantic | | | |
| Procedural | | | |

### 3. Write policy

> _When and what does Cumin write? e.g. after every turn? on task completion? on error?_

### 4. Read / retrieval policy

> _How does Cumin decide what to recall? Give a ranking/scoring approach._

### 5. Memory API (pseudocode)

```python
# write your pseudocode here
```

### 6. Agent-loop integration (pseudocode)

```python
# show a single Cumin turn: recall -> act -> write
```

### 7. Failure modes & mitigations

| Failure mode | Mitigation |
|---|---|
| | |
| | |
| | |

### 8. (Bonus) Compaction

> _Over time, episodic memory grows unbounded. How do you summarize/compact it?_