Agent Memory on FrenchForet

The Memory Problem

Mon, 01 Jan 0001 00:00:00 +0000

Goal: understand that two different things are both called “memory,” and that this course is about the more difficult one. Context management keeps a single conversation consistent while staying within the token budget. Memory is what an agent knows across sessions, days, and topics — after the conversation that created it has ended. You already built the first one. The second is a database-and-retrieval problem, and it is large enough to be its own course.

A Taxonomy of Memory

Mon, 01 Jan 0001 00:00:00 +0000

Goal: get a vocabulary before you build. “Memory” is not one thing — an agent has several kinds, each with its own content, lifecycle, and storage. This unit describes a practical taxonomy (working, episodic, semantic, procedural, plus profile and derived). It helps you answer the one question that matters before you write code: which of these does my agent actually need? Build the kinds your problem requires; skip the rest.

The Naive Baseline

Mon, 01 Jan 0001 00:00:00 +0000

Goal: build the simplest memory that could work — persist conversation turns to SQLite and recall them by recency and keyword — and then watch it fail on purpose. This is the baseline that every later piece improves on. You cannot see the value of embeddings (Unit 3) or a graph (Unit 5) until you reach the limit that this baseline reaches.

Where this fits: Unit 1 named the kinds of memory; this is the first persistent store. It needs no endpoint and no Docker — only Python’s standard-library sqlite3 — so it runs anywhere. We build semantic/episodic memory in the most basic way on purpose.

Semantic Recall with Embeddings

Mon, 01 Jan 0001 00:00:00 +0000

Goal: fix the biggest problem in the Unit 2 baseline. Embed each remembered fact as a vector and recall by meaning — using cosine similarity — so a user’s question retrieves the right fact even when the question uses very different words than the stored text. This is the same method as foundations §19–20, now applied to memory instead of documents.

Where this fits: Unit 2’s keyword recall failed on “where do I live?” and “what seafood am I allergic to?” because it matched strings, not meaning. Embeddings fix exactly that gap. But they create the next limitation — each fact is an independent point — which is what leads us toward a graph in Unit 4. This unit needs EMBED_MODEL; without it the script skips cleanly and you can still read along.

Why a Graph

Mon, 01 Jan 0001 00:00:00 +0000

Goal: make the central decision of this course honestly. A graph is more work than a vector store — Docker, a schema, extraction, traversal. When is that extra complexity worth it, and when does it only cost you tokens and latency for no benefit? This unit describes the three storage models, the real (conditional) evidence, and a clear rule for when to move to a graph.

Where this fits: Unit 3 brought you to the limit — semantic recall fixed wording but could not correlate facts. This unit decides whether to move to a graph. It is a “decide” unit: no new code, but the argument that justifies all the building in Units 5–7. Move to a graph on purpose, or do not move at all.

Modeling Memory as a Graph

Mon, 01 Jan 0001 00:00:00 +0000

Goal: start a real graph database (Neo4j, via Docker) and model a conversation’s memory in it by hand — sessions, turns, entities, and a small vocabulary of relationships — writing the nodes and edges yourself in Cypher. By the end you will run a multi-hop query that answers a question no single stored fact contains, and see why a row in a table or a chunk in a vector store cannot give you this.

Ingestion: Extracting Structure

Mon, 01 Jan 0001 00:00:00 +0000

Goal: stop writing nodes and edges by hand. Give an LLM a raw conversational turn, have it produce (entity, relation, entity) triples, validate that output, and MERGE it into the same graph you built in Unit 5 — then embed each entity so later units can do hybrid (graph + vector) recall. Along the way you will meet the problem that controls every real memory system: deduplication — deciding when two mentions are the same thing.

Retrieval & Context Assembly

Mon, 01 Jan 0001 00:00:00 +0000

Goal: get facts back out of the memory graph and into a prompt. You will read the graph two different ways — entity-match traversal when you know the starting node, and broad meaning recall when you only have a vague question — then combine them, rerank the results by recency, importance, and relevance, assemble the top facts into the prompt, and wrap the whole thing as a search_memory tool the agent can call on its own.

Curation & Lifecycle

Mon, 01 Jan 0001 00:00:00 +0000

Goal: keep the memory graph healthy over time. So far it only grows: every turn adds nodes and edges (Unit 6), and retrieval assumes the right facts are in there (Unit 7). But a memory that only grows becomes noise — old trivia crowds out what matters, and recall gets worse, not better. This unit adds the lifecycle: a decay score that fades memories over time but is reinforced by access, a forgetting pass that drops what is both faded and unimportant, and a promotion gate that decides what is even worth storing — narrating its decision before it writes.

Measure Before You Optimize

Mon, 01 Jan 0001 00:00:00 +0000

Goal: put a number on how good your memory recall actually is. Units 7 and 8 added knobs — decay rate, importance thresholds, top-k, hybrid weights — and every one changes what gets retrieved. Without measurement, tuning them is guessing. This unit builds the four standard retrieval metrics — recall@k, precision@k, MRR, and nDCG@k — over a small labeled set, so the choices from the last two units become measured, not asserted.

Observability & Privacy

Mon, 01 Jan 0001 00:00:00 +0000

Goal: treat memory as what it is — durable, personal data — and build the two operational habits that follow. Observability: every memory read and write emits a structured log line that is joinable to the request that caused it, so you can answer “what did the agent remember, and recall, for this conversation?” Privacy: memory is scoped to an owner, recall filters by who is asking, personal data is redacted before it reaches a log, and every query binds its values so an attacker cannot rewrite it.

The Opinionated Default

Mon, 01 Jan 0001 00:00:00 +0000

Goal: put it all together. In one agent loop you will wire ingestion (Unit 6), the graph (Unit 5), hybrid retrieval (Unit 7), the lifecycle gate (Unit 8), and the controls from Units 9–10 into a single memory-backed agent — then step back and answer the question the whole course has been building toward: when is this machine worth building, and when should you not build it at all?

Where this fits: this is the synthesis. Every prior unit built one piece in isolation so you could see it clearly. Here the pieces become one system, and the course delivers its opinion — a defensible default, with the honest boundaries around it.