State & Memory Architecture

A key aspect of a virtual companion is conversational recall. If you mention your name or your favorite food in one turn, Yumi must remember it dynamically in the next.

Here is a breakdown of Yumi's memory architecture.

🧠 LangGraph State & Memory Saver

Yumi is orchestrating conversations using LangGraph. The workflow utilizes a persistent checkpointer to load and store chat history.

In src/yumi/agent/graph.py, the memory checkpointer is initialized:

from langgraph.checkpoint.memory import InMemorySaver

# ...
saver = InMemorySaver()
return workflow.compile(checkpointer=saver)

Session IDs: Every WebSocket connection is assigned a persistent session identifier (e.g. yumi_session_1).
Message Buffering: When the LLM generates a response in nodes.py, both your human message and Yumi's AI response are appended to the LangGraph history:
```
messages_to_append = [
    new_human_message,
    AIMessage(content=structured_response.response_text),
]
```

Technical Details: Prototype vs. Production Memory

Prototype (InMemorySaver): The current architecture holds message history inside active RAM memory. This is optimized for ultra-fast, zero-overhead access. However, restarting the python server clears the memory.
Production Migration (SQLite / PostgreSQL): For permanent memory that survives server reboots, the checkpointer can be swapped from InMemorySaver to standard SqliteSaver or PostgresSaver with just a few lines of code inside graph.py.

Proceed to the Writing Custom Tools page to extend her functional capabilities!