clean up and reorganize

Author: retroryan

Lab_5_Foundry_Agents/README.md

@@ -4,7 +4,9 @@ In this lab, you'll build your first intelligent agents using the **Microsoft Ag
 
 ## What is the Microsoft Agent Framework?
 
-The [Microsoft Agent Framework](https://github.com/microsoft/agent-framework) is a production-ready framework for building AI agents that can reason, use tools, and maintain context across conversations. It provides:
+The [Microsoft Agent Framework](https://github.com/microsoft/agent-framework) is a production-ready framework for building AI agents that can reason, use tools, and maintain context across conversations. At its core, it solves a fundamental problem: LLMs are stateless. Every time you send a message, the model has no memory of previous interactions and no access to your data. The agent framework bridges this gap by orchestrating a lifecycle around each LLM invocation — injecting relevant knowledge before the call (via context providers), giving the model the ability to take actions (via tools), and extracting useful information from the response afterward. This turns a bare LLM into an agent that can retrieve, reason, and act.
+
+The framework provides:
 
 - **Agents** — AI systems that receive instructions, use tools, and generate responses via an LLM
 - **Tools** — Python functions the agent can decide to call based on the user's query

Lab_6_Context_Providers/README.md

@@ -2,6 +2,46 @@
 
 In this lab, you'll learn how to use **context providers** with the Microsoft Agent Framework (MAF) to automatically inject knowledge graph context into agent conversations. Instead of defining tools that the agent must explicitly call, context providers run automatically before each agent invocation, enriching the LLM with relevant information from your Neo4j knowledge graph.
 
+## What is Neo4jContextProvider?
+
+The notebooks in this lab use `Neo4jContextProvider` from the [`agent-framework-neo4j`](https://github.com/neo4j-labs/agent-framework-neo4j) package. It's a MAF context provider that connects your agent to a Neo4j knowledge graph, automatically searching for relevant content and injecting it into the LLM's context window before every invocation.
+
+### How It Works
+
+When the agent receives a query, the provider's `before_run()` hook:
+
+1. Takes the most recent messages from the conversation (configurable via `message_history_count`, default 10)
+2. Concatenates the message text into a single search query
+3. Executes a search against a Neo4j index (vector, fulltext, or hybrid)
+4. Formats the results with scores and metadata (e.g., `[Score: 0.892] [company: Apple Inc]`)
+5. Injects the formatted context into the agent's session via `context.extend_messages()`
+
+The LLM then sees this context alongside the user's question and can ground its answer in real knowledge graph data.
+
+### Search Modes
+
+The provider supports three search modes via the `index_type` parameter:
+
+| Mode | How It Works | Best For |
+|------|-------------|----------|
+| **`vector`** | Converts query to an embedding, searches a vector index by cosine similarity | Finding conceptually related content even when keywords don't match |
+| **`fulltext`** | Tokenizes query, searches a fulltext index using BM25 scoring | Finding content with specific terms and exact phrases |
+| **`hybrid`** | Runs both vector and fulltext searches, combines scores | Comprehensive retrieval combining semantic understanding and keyword matching |
+
+### Graph Enrichment
+
+The provider's most powerful feature is **graph enrichment** via the `retrieval_query` parameter. After the initial index search finds matching nodes, a custom Cypher query traverses the graph to pull in related entities — company names, products, risk factors, executives — giving the LLM much richer context than the matched text alone.
+
+The provider automatically selects the right underlying retriever based on your configuration:
+
+| index_type | retrieval_query | Retriever Used |
+|------------|-----------------|----------------|
+| `vector` | Not set | `VectorRetriever` |
+| `vector` | Set | `VectorCypherRetriever` |
+| `fulltext` | Any | `FulltextRetriever` |
+| `hybrid` | Not set | `HybridRetriever` |
+| `hybrid` | Set | `HybridCypherRetriever` |
+
 ## Prerequisites
 
 Before starting, make sure you have:

Lab_7_Agent_Memory/README.md

@@ -2,6 +2,40 @@
 
 In this lab, you'll learn how to give agents **persistent memory** using the `neo4j-agent-memory` package with the Microsoft Agent Framework. Unlike the knowledge graph context providers in Lab 6 that retrieve from a static knowledge base, agent memory enables agents to remember conversations, learn user preferences, extract entities, and recall similar past interactions — all stored in Neo4j.
 
+## What is Neo4j Agent Memory?
+
+The notebooks in this lab use the [`neo4j-agent-memory`](https://github.com/neo4j-labs/agent-memory) package — a graph-native memory system that gives AI agents persistent, searchable memory stored in Neo4j. While the knowledge graph context providers in Lab 6 retrieve from a static knowledge base you built, agent memory is dynamic: it grows with every conversation as the agent learns user preferences, extracts entities, and records its own reasoning.
+
+### Three Memory Types
+
+**Short-Term Memory** stores conversation history as `Message` nodes with embeddings. This lets the agent semantically search past messages — not just replay them in order, but find the most relevant past exchanges for the current question. Messages are grouped into conversations by session, and entities are automatically extracted during ingestion.
+
+**Long-Term Memory** stores structured knowledge as entities, facts, and preferences. Entities (people, organizations, locations, etc.) are deduplicated using configurable strategies (exact, fuzzy, semantic, or composite matching). Facts are stored as Subject-Predicate-Object triples (e.g., "Apple → manufactures → iPhone"). Preferences capture user-specific information with category and context.
+
+**Reasoning Memory** captures traces of past agent behavior — what tasks were attempted, what tools were called, whether they succeeded or failed, and how long they took. When the agent encounters a similar task later, it can retrieve these traces to learn from its own experience.
+
+### Memory Context Provider
+
+The package provides its own `Neo4jContextProvider` (distinct from the one in Lab 6) that integrates with MAF:
+
+- **`before_run()`** retrieves context from all three memory types: recent conversation history, semantically relevant past messages, matching preferences, related entities, and similar reasoning traces
+- **`after_run()`** stores the new messages and automatically extracts entities from the conversation
+
+### Memory Tools
+
+Beyond automatic context injection, the package provides six callable tools via `create_memory_tools()` that give the agent explicit control over its memory:
+
+| Tool | Purpose |
+|------|---------|
+| `search_memory` | Search across all memory types (messages, entities, preferences) |
+| `remember_preference` | Save a user preference with category and context |
+| `recall_preferences` | Retrieve saved preferences by topic |
+| `search_knowledge` | Query the knowledge graph for entities by type |
+| `remember_fact` | Store a factual relationship as a Subject-Predicate-Object triple |
+| `find_similar_tasks` | Retrieve similar past reasoning traces to learn from experience |
+
+In Notebook 01, you'll use the **context provider** for automatic memory. In Notebook 02, you'll combine context providers with **memory tools** so the agent can both passively recall and actively manage its memory.
+
 ## Prerequisites
 
 Before starting, make sure you have: