In the previous chapter, Interleaved Thinking, we taught our agent to "think" before it acts. It can now plan complex tasks and catch its own mistakes.
However, we still have a major flaw. As soon as the script finishes running, the agent forgets everything. If you tell the agent your name is "Sarah" today, and come back tomorrow, it will ask: "Who are you?"
Current LLMs have Amnesia.
Imagine you are building a medical assistant.
Without Memory: The agent sees "Strep throat" -> retrieves standard medical advice -> Suggests Amoxicillin (a penicillin derivative). This is dangerous.
With Memory: The agent looks up your profile -> sees "Allergy: Penicillin" -> Suggests Azithromycin instead.
In this chapter, we will build a Structured Memory System to save the agent from making dangerous mistakes.
We don't just want to save the entire chat log (that's messy and expensive). We want to save Structured Facts.
The simplest memory. We just write down everything that happened in a file (usually .jsonl). It is perfect for auditing, but hard for the AI to read quickly because it gets too long.
We turn text into numbers (vectors). When you ask a question, the system finds past notes that "sound similar" to your question. This is often called RAG (Retrieval-Augmented Generation).
This is the most powerful form of structured memory. We store specific relationships between entities.
This structure allows the agent to answer specific questions like "What is Sarah allergic to?" with 100% accuracy, rather than guessing.
Let's build a simple Knowledge Graph system for our Doctor Agent. We will treat memory as a Tool that the agent can read from and write to.
We need a strict format. We don't want the agent scribbling random notes. We want "Triples" (Subject -> Relation -> Object).
# A single memory unit
fact = {
"subject": "User",
"relation": "has_allergy",
"object": "Penicillin",
"valid_from": "2023-10-27"
}
Explanation: By forcing this structure, we make it easy for the code to filter data later.
We need a function that saves this JSON object to a file.
import json
def save_fact(fact_dict):
"""Appends a fact to our long-term storage file."""
with open("memory.jsonl", "a") as f:
f.write(json.dumps(fact_dict) + "\n")
return "Fact saved successfully."
Explanation: We use "Append mode" ("a"). We never delete old facts; we just add new ones. This builds a history of the patient.
When the user asks a question, we check our database.
def get_facts(subject, relation=None):
"""Finds all facts about a specific subject."""
memories = []
with open("memory.jsonl", "r") as f:
for line in f:
data = json.loads(line)
if data['subject'] == subject:
memories.append(data)
return memories
Explanation: This is a simplified search. In a real production system (using tools like Zep, Mem0, or Cognee), this logic is handled by a specialized database that is much faster.
How does the agent know when to use memory? We integrate it into the loop we built in Chapter 4: Interleaved Thinking.
The flow changes from Think -> Act to Recall -> Think -> Act -> Memorize.
We don't want to manually write Python code for every fact. We want the Agent to decide what to save. We do this by giving the Agent a specialized tool called memorize_fact.
We give this tool to the LLM (refer to Chapter 3: Tool Design).
memorize_tool = {
"name": "memorize_fact",
"description": "Save a permanent fact about the user. Use this when the user tells you about preferences, allergies, or history.",
"parameters": {
"properties": {
"relation": {"type": "string", "description": "e.g. 'likes', 'lives_in'"},
"object": {"type": "string", "description": "The value of the fact"}
}
}
}
Now, when the user says "I moved to Seattle," the Agent's internal monologue (Interleaved Thinking) kicks in:
memorize_fact(relation="lives_in", object="Seattle")memory.jsonl.You might ask: "Why not just save the user's sentence 'I moved to Seattle' directly?"
If we save raw text, the agent has to read and re-process that text every time.
By saving User -> lives_in -> Seattle, we create a Knowledge Graph.
This allows for powerful logic later:
lives_in. Result: Seattle. Check if Seattle is coastal. Result: Yes.
In production, you rarely write raw JSONL files. You use specialized frameworks (detailed in the memory-systems skill) that handle the heavy lifting:
In this chapter, we solved the "Amnesia" problem.
Subject -> Relation -> Object is better than storing raw text.Now our agent is smart, thoughtful, and has a long-term memory. But so far, we have only been building one agent.
What happens if the "Doctor Agent" needs to talk to a "Scheduling Agent" to book an appointment? How do they talk to each other without confusing the user?
Next Chapter: Multi-Agent Architecture
Generated by Code IQ