diff --git a/dev-rel-agent-memory/connect-to-env/connect-to-env.md b/dev-rel-agent-memory/connect-to-env/connect-to-env.md new file mode 100644 index 000000000..e56996ea1 --- /dev/null +++ b/dev-rel-agent-memory/connect-to-env/connect-to-env.md @@ -0,0 +1,56 @@ +# Connect to the Development Environment + +## Introduction + +In this lab, you'll learn how to access the web-based JupyterLab development environment, where you can write and run Python code directly in your browser. You'll log in, and get ready to start coding in a hands-on environment. + +Estimated Time: 5 minutes + +### Objectives + +* Login to JupyterLab server +* Run Jupyter Notebook + +## Task 1: Login to JupyterLab Server and open the correct notebook + +Estimated Time: 2 minutes + +1. To navigate to the development environment, click **View Login Info**. Copy the Development IDE Login Password. Click the Start Development IDE link. + + ![Open Development Environment](./images/dev-env.png =50%x*) + +2. Paste in the Development IDE Login Password that you copied in the previous step. Click **Login**. + + ![JupyterLab server login](./images/jupyter-login.png " ") + +1. Select **`notebooks/agent_memory`** directory to open it. Double click on one of two files **`notebook_student_oci.ipynb`**, and **`notebook_student_ollama.ipynb`** depending on what the instructor tells you, and that file will open in the the panel on the right. + + ![Open Launcher](./images/launcher.png " ") + +## Task 2: Learn to utilize Agent Memory in your AI apps + +You will use a Jupyter Notebook in a JupyterLab server to build and test database queries. If you are new to notebooks, the following tips will help you get started and work smoothly. + +Estimated Time: 35-45 minutes + +1. **Executing Code Blocks**: You can run code in two simple ways: press **Shift+Enter** to execute and move to the next cell, or click the **Play/Execute** button in the menu bar at the top of this tab. Both methods work interchangeably. + +2. **Block Types**: Instructions and code are separated into **their own blocks**. Instructions are in markdown (like this cell), while code is in executable Python blocks. If you accidentally run an instruction block, it’ll just skip to the next cell—no harm done! + +3. **Running Indicators**: When you run a code block, its label changes from `[ ]` (empty) or `[1]` (a number) to `[*]`. The asterisk (`*`) means it’s processing. Wait until it switches back to a number (e.g., `[2]`) before moving on, ensuring the operation is complete. + +4. **Output & Warnings**: Below each code cell, output appears during and after execution. This can include results, visualizations, or messages. Warnings may show up—these are usually informational, such as notices about deprecated features. Unless an error halts execution, users can continue without making changes. If you see a error, review the code for any issues and make changes accordingly and try executing the cell again. + + **NOTE:** Look for **green text** as in the image below where it says "Connected successfully!". Many cells will have different message, but the final successful one should always be green. When you see the green text, the cell completed. For some longer running cells, this is important to watch for. + + ![JupyterLab cell example](./images/block.png " ") + +## Conclusion + +In this lab you logged into the **IDE Development Environment** for Jupyter Labs. You launched the **`notebook_student_*.ipynb`** notebook and worked through the notebook to learn about using Agent Memory with your AI application development. + +Make sure you take the quiz by clicking on **Take the quiz!** link on the left nav bar. + +## Acknowledgements +* **Authors** - Kirk Kirkconnell +* **Last Updated By/Date** - Kirk Kirkconnell, June 2026 diff --git a/dev-rel-agent-memory/connect-to-env/images/block.png b/dev-rel-agent-memory/connect-to-env/images/block.png new file mode 100644 index 000000000..02ad04838 Binary files /dev/null and b/dev-rel-agent-memory/connect-to-env/images/block.png differ diff --git a/dev-rel-agent-memory/connect-to-env/images/dev-env.png b/dev-rel-agent-memory/connect-to-env/images/dev-env.png new file mode 100644 index 000000000..e63e81594 Binary files /dev/null and b/dev-rel-agent-memory/connect-to-env/images/dev-env.png differ diff --git a/dev-rel-agent-memory/connect-to-env/images/jupyter-login.png b/dev-rel-agent-memory/connect-to-env/images/jupyter-login.png new file mode 100644 index 000000000..c3ba1fde6 Binary files /dev/null and b/dev-rel-agent-memory/connect-to-env/images/jupyter-login.png differ diff --git a/dev-rel-agent-memory/connect-to-env/images/launcher.png b/dev-rel-agent-memory/connect-to-env/images/launcher.png new file mode 100644 index 000000000..84badbe7f Binary files /dev/null and b/dev-rel-agent-memory/connect-to-env/images/launcher.png differ diff --git a/dev-rel-agent-memory/introduction/introduction.md b/dev-rel-agent-memory/introduction/introduction.md new file mode 100644 index 000000000..e7b2d9f63 --- /dev/null +++ b/dev-rel-agent-memory/introduction/introduction.md @@ -0,0 +1,73 @@ +# Introduction + +## About this Workshop + +In this lab, we'll interact with a data set from an application named Prism CityOps, but we will add new database objects combined with the oracleagentmemory Python driver to enable our AI agent to have a memory lifecycle. Prism CityOps is an application used by the city of Kirkland to monitor and manage city infrastrucuter such as ongoing maintenance, active monitoring via IoT devices, crew dispatch, record keeping, and more. This new capability you'll build will help with more in-depth reporting, more informed alerting, and much more. + +You'll utilize a Jupyter Notebook with real Python code, completing real activities, to build this agent with fully fleshed out agents. + +Estimated Workshop Time: 45 - 55 minutes + +✅ **Overview of Labs** + +This notebook builds a field-assistant copilot for city infrastructure inspectors using Oracle AI Database, Ollama, and the oracleagentmemory SDK. Learners see how inspection narratives become durable memory that can help future inspectors reason from prior work instead of starting from scratch. + +* **The data and memory layer** +This section introduces the difference between domain data and agent memory. Learners see how CITY_ASSET and CITY_INSPECTION_FINDING act as the system of record, while SDK-managed tables such as CITY_MESSAGE and CITY_MEMORY capture conversations and extracted facts, preferences, guidelines, and memories. + +* **Design** +This section explains the copilot’s read-then-write cycle: gather context, ask the LLM, persist the turn, and let the SDK derive reusable memory. Learners understand how asset records, context cards, vector search, and automatic memory extraction combine into a single copilot workflow. + +* **Part 1: Oracle setup** +This section connects the notebook to Oracle AI Database and establishes the shared database connection used throughout the workshop. Learners confirm that the SDK tables, custom domain tables, and vector-search operations all live in the same converged database environment. + +* **Part 2: The embedder and SDK** +This section wires Oracle’s in-database ONNX embedding model into the SDK through an embedder adapter. Learners initialize OracleAgentMemory with Ollama for local extraction and see how text becomes database-computed vectors without external embedding calls. + +* **Part 3: City asset + auto-extraction** +This section loads the city asset registry and demonstrates how raw maintenance narratives become typed memory records. Learners build report_event, trigger SDK extraction with add_messages, and verify that messages and extracted memories were persisted. + +* **Part 4: Inspection findings + similar-finding search** +This section creates a structured inspection-finding workflow separate from SDK memory. Learners build log_finding and find_similar_findings, then use Oracle vector search with relational filters to retrieve prior findings by asset, category, and semantic similarity. + +* **Part 5: Scoping - inspector vs city** +This section demonstrates how memory visibility is controlled by user_id, agent_id, and thread_id. Learners verify that one inspector’s private notes do not leak to another inspector, while shared city or asset-level knowledge remains available when intentionally scoped that way. + +* **Part 6: The cityops copilot - End-to-end** +This section assembles the earlier components into call_copilot, the full copilot turn. Learners combine asset lookup, thread context, asset-pooled memory, similar-finding search, LLM reasoning, and write-back into one working assistant flow. + +* **The cross-inspector handoff scenario** +This section shows how Inspector Mercer’s Harbor Bridge findings help Inspector Vance later, without a direct human handoff. Learners see the difference between diagnostic copilot interaction, formal finding capture, and reusable memory that carries forward across inspectors. + +* **Compare: Vance with and without memory** +This section contrasts the same inspection narrative with and without memory-backed context. Learners see why memory changes the quality of the copilot’s answer by surfacing prior findings, guidelines, and asset-specific history. + +* **Key takeaways and memory types** +The closing sections summarize the layers learners built and map SDK record types to broader agent-memory concepts. Learners connect concrete database tables and SDK features to semantic memory, episodic memory, working context, persona preferences, and shared coordination memory. + +### Objectives + +* Connect to Oracle AI Database and initialize the shared database environment used by the copilot. +* Configure an Oracle in-database ONNX embedder and initialize the oracleagentmemory SDK with a local Ollama model. +* Load city infrastructure assets and use SDK auto-extraction to turn inspection narratives into typed memory records. +* Create and query structured inspection findings with Oracle vector search and relational filters. +* Explain how memory scoping prevents private inspector notes from leaking while still supporting shared city or asset-level knowledge. +* Build an end-to-end call_copilot workflow that combines asset lookup, context cards, memory search, similar-finding search, LLM reasoning, and persistence. +* Demonstrate how one inspector’s prior work can improve another inspector’s later diagnosis without exposing raw private conversations. +* Compare copilot responses with and without memory to evaluate the practical value of agent memory in an operational workflow. + +### Prerequisites + +This lab assumes you have: + +* An Oracle account to submit your LiveLabs Sandbox reservation. +* Basic knowledge of coding and Python. +* Basic knowledge of Oracle Database, i.e., how to run queries. + +## Learn More + +* [Oracle AI Database Documentation](https://docs.oracle.com/en/database/oracle/oracle-database/26/) + +## Acknowledgements +* **Authors** - Kirk Kirkconnell +* **Last Updated By/Date** - Kirk Kirkconnell, June 2026 diff --git a/dev-rel-agent-memory/quiz/images/badge.png b/dev-rel-agent-memory/quiz/images/badge.png new file mode 100644 index 000000000..b7d752677 Binary files /dev/null and b/dev-rel-agent-memory/quiz/images/badge.png differ diff --git a/dev-rel-agent-memory/quiz/quiz.md b/dev-rel-agent-memory/quiz/quiz.md new file mode 100644 index 000000000..1c1fde096 --- /dev/null +++ b/dev-rel-agent-memory/quiz/quiz.md @@ -0,0 +1,82 @@ +# Quiz + +## Introduction + +Test your knowledge of building with agent memory! This quiz covers key concepts from the presentation and lab including types of agent memory, what each type is best for, and how to use them effectively. + +Estimated Time: 5 minutes + +```quiz-config + passing: 80 + badge: images/badge.png +``` + +### Objectives + +* To pass the quize and get your **Zero to Hero: Agent Memory** Skills Badge! + +### Quiz Questions + +```quiz score + +Q: What are the three types of long-term memory in Agent Memory? +- Entity, conversational, and persona memory +* Procedural, episodic, and semantic memory +- Volatile, inconsistent, and passive-aggressive memory +- Goldfish mode, 'What did I come in here for?' mode, and 'I'll remember this later, I promise' memory +> Procedural, episodic, and semantic memories branch out to the Execution, Experiece, and Knowledge layers respectively to enable your application to store and utilize all kinds of data long-term. + +Q: What is the difference between domain data and memory in the lab? +- Domain data is created by Ollama, while memory is loaded from JSON files +- Domain data is private to each inspector, while memory is always public +- Domain data stores prompts, while memory stores only embeddings +* Domain data is the system of record, while memory is what the agent accumulates from interactions +> `CITY_ASSET` and `CITY_INSPECTION_FINDING` hold structured operational data, while SDK-managed memory tables store conversations and extracted facts, preferences, guidelines, and memories. + +Q: Why does the notebook use an in-database ONNX embedding model? +- To fine-tune Ollama on inspection findings +- To convert SQL tables into Markdown summaries +* To compute vector embeddings inside Oracle without sending text to an external embedding service +- To disable vector search during the lab +> The embedder adapter exposes Oracle’s in-database embedding capability to the SDK, keeping embedding generation close to the data, but as with anything there are trade-offs. + +Q: What happens when `thread.add_messages(...)` runs with memory extraction enabled? +- The SDK drops and recreates all `CITY_` tables +* The SDK stores the message and uses an extractor LLM to create typed memory records +- The LLM directly inserts rows into `CITY_ASSET` +- The notebook bypasses the database and stores memory only in Python +> `add_messages` writes conversational history and triggers SDK extraction into records such as facts, preferences, guidelines, and memories. + +Q: Why are inspection findings stored in `CITY_INSPECTION_FINDING` instead of only in SDK memory? +* Findings are structured domain records with fields like category, severity, recommendation, grade, and embedding +- SDK memory cannot store any text +- Findings must be visible to every database user without filtering +- Findings are temporary and should disappear after each notebook run +> Inspection findings are part of the formal system of record, so the lab stores them in a dedicated SQL table with a vector column for semantic search. + +Q: What does `find_similar_findings` demonstrate? +- Vector search requires exporting all findings to a separate service +- Similarity search only works if the inspector names match exactly +- The LLM must manually rank all findings +* Oracle can combine vector similarity with relational filters in one SQL query +> The function searches semantically similar findings while also filtering by fields such as asset and category. + +Q: What does the scoping section teach about inspector memory? +- Every inspector can read every raw conversation by default +* Private inspector notes are isolated by scope, while intentionally shared city or asset knowledge can still be retrieved +- Scoping happens only in the notebook UI +- Memory records are scoped by file path instead of database fields +> The lab uses `user_id`, `agent_id`, and `thread_id` as SQL-backed scope controls to prevent unintended cross-inspector leakage. + +Q: In the cross-inspector handoff scenario, how does Vance benefit from Mercer’s earlier work? +- Vance receives Mercer's entire message history by default +- Mercer manually forwards her notebook output to Vance +- The LLM guesses what Mercer probably observed +* The copilot retrieves Mercer's logged findings and extracted asset-level memory without exposing her raw private conversation +> The handoff works because structured findings and asset-pooled extracted memories are retrievable for the same asset while private thread history remains scoped. + +``` + +## Acknowledgements +* **Authors** - Kirk Kirkconnell +* **Last Updated By/Date** - Kirk Kirkconnell, January 2026 diff --git a/dev-rel-agent-memory/workshops/sandbox/index.html b/dev-rel-agent-memory/workshops/sandbox/index.html new file mode 100644 index 000000000..aebbdda4a --- /dev/null +++ b/dev-rel-agent-memory/workshops/sandbox/index.html @@ -0,0 +1,63 @@ + + + + + + + + + Oracle LiveLabs + + + + + + + + + + + + + +
+
+
+
+
+
+
+
+ + + + + diff --git a/dev-rel-agent-memory/workshops/sandbox/manifest.json b/dev-rel-agent-memory/workshops/sandbox/manifest.json new file mode 100644 index 000000000..01defc4b9 --- /dev/null +++ b/dev-rel-agent-memory/workshops/sandbox/manifest.json @@ -0,0 +1,26 @@ +{ + "workshoptitle": "From Zero to Hero: Agent Memory", + "help": "livelabs-help-database_us@oracle.com", + "tutorials": [ + { + "title": "Introduction", + "description": "The Introduction is always first. The title and contents menu title match for the Introduction.", + "filename": "../../introduction/introduction.md" + }, + { + "title": "Connect to the Development Environment", + "description": "This is a step-by-step guide showcasing how the hands-on lab instance is navigated", + "filename": "../../connect-to-env/connect-to-env.md" + }, + { + "title": "Take the quiz!", + "description": "You can take the quiz and get a Skills Badge!", + "filename": "../../quiz/quiz.md" + }, + { + "title": "Need Help?", + "description": "Solutions to Common Problems and Directions for Receiving Live Help", + "filename": "https://livelabs.oracle.com/cdn/common/labs/need-help/need-help-freetier.md" + } + ] +} \ No newline at end of file