Oracle AI Agent Memory Demo

This repository is a standalone Python example for using oracleagentmemory with the OpenAI SDK and a local Oracle Database Free container.

The demo shows how agent memory can combine several Oracle Database capabilities:

• Facts: durable memories plus relational customer/device/case records.
• Relationships: Oracle SQL Property Graph / GRAPH_TABLE paths over constrained tables with enforced graph metadata.
• Context: threads, messages, summaries, and context cards.
• State: native Oracle JSON support-case state updated with JSON_MERGEPATCH.
• Similarity: Oracle vector search through Agent Memory record chunks.
• Scoped access: user, agent, and thread memory boundaries.

Prerequisites

• Python 3.10 or newer
• Docker
• uv
• An OpenAI API key

The demo uses gvenzl/oracle-free:23.26.1-slim-faststart by default. That is the local Oracle Database Free 23ai/23c substrate for Oracle AI Agent Memory 26.4.x. The container is configured with a dedicated demo application user so the managed Agent Memory schema is not created in the SYSTEM tablespace.

Quickstart

cp .env.example .env
# Edit .env and set OPENAI_API_KEY.
uv sync
uv run agent-memory-demo run

The run command starts an Oracle container, creates demo schema objects, seeds deterministic data, runs a scripted support conversation, shows memory tool usage, prints the final assistant answer, and includes a database inspection report before the container is torn down.

Before the capstone OpenAI agent turn, run walks through the core oracleagentmemory API directly. You will see labelled calls for user and agent profiles, thread creation, message ingestion, durable memory, memory.get_thread, thread.search, broad-vs-exact thread matching, cross-user scope isolation, thread.get_context_card, and thread.get_summary.

The CLI output is color-coded so the moving pieces are easier to follow:

• Green: user messages.
• Magenta: assistant messages.
• Yellow: OpenAI tool calls and their JSON arguments.
• Blue: Oracle database, graph, and tool-result evidence.
• Cyan: progress and memory setup/search visibility.

Commands

uv run agent-memory-demo run

Runs the full scripted demo.

uv run agent-memory-demo interactive

Starts an interactive memory-enabled assistant using the same command-scoped Oracle container lifecycle. The command seeds the same companion demo data and stores your turns in a scoped Agent Memory thread.

uv run agent-memory-demo inspect-db

Starts a fresh Oracle container, seeds deterministic demo data, and prints row counts, JSON case state, and graph relationship paths. This command does not create Agent Memory records, so managed memory table counts are expected to be zero; use verify-memory or run to populate memory and vector chunk tables.

uv run agent-memory-demo verify-memory

Starts a fresh Oracle container, seeds companion data plus explicit Agent Memory case summaries, then verifies both Oracle SQL Property Graph traversal and vector-backed similar-case retrieval. It also prints Oracle metadata evidence for the managed OAM_DEMO_RECORD_CHUNKS table, including row count, VECTOR columns, and vector indexes.

uv run agent-memory-demo reset-db

Exercises the destructive companion-schema reset path and recreates the managed Agent Memory schema with SchemaPolicy.RECREATE inside a command-scoped container.

Configuration

Copy .env.example to .env and set OPENAI_API_KEY.

Important defaults:

• OPENAI_MODEL=gpt-5-mini
• OPENAI_EMBEDDING_MODEL=text-embedding-3-small
• OPENAI_MEMORY_LLM_MODEL=gpt-5-mini
• ORACLE_FREE_IMAGE=gvenzl/oracle-free:23.26.1-slim-faststart
• ORACLE_MEMORY_TABLE_PREFIX=OAM_DEMO_
• ORACLE_APP_TABLE_PREFIX=OAM_DEMO_APP_

The OpenAI SDK drives the assistant tool-calling loop. Oracle Agent Memory uses LiteLLM-compatible Embedder and Llm adapters configured from the same environment. gpt-5-mini is the verified default model and can be overridden with OPENAI_MODEL and OPENAI_MEMORY_LLM_MODEL.

What To Look For

The scripted demo intentionally makes memory behavior visible:

• The demo creates both user and agent actor profiles.
• Thread 1 stores a support conversation containing durable facts.
• The demo prints Checking for auto-extracted memories....
• An explicit durable memory records Alex's router and contact preferences.
• Thread 2 retrieves earlier context for a follow-up support issue.
• The walkthrough reopens Thread 1 by ID, shows broad vs exact thread.search behavior, demonstrates that user_blair cannot see Alex's memories, and prints Thread 1's context card and summary.
• Tool calls search memory, save memory, inspect graph relationships, update JSON state, and inspect database tables. The run command prints each tool call with its JSON arguments and a compact Oracle result summary.
• The inspection report shows managed Agent Memory tables and app-owned companion tables, including JSON case state and graph vertex/edge tables.
• verify-memory prints explicit graph paths, Agent Memory vector chunk storage metadata, and vector-backed similarity search results, including the expected prior router case case_wifi_dropout_001.

Seed Data

The demo seed data lives in src/agent_memory_demo/data/demo_seed.json. It includes multiple users, accounts, devices, support cases, policies, graph vertices/edges, and explicit Agent Memory records used for vector similarity checks.

The default scenario still centers on Alex and the River House account, but the fixture includes additional thermostat and camera cases so scoped retrieval can distinguish similar router cases from unrelated customer histories.

Inspect The Database Yourself

For a quick database evidence report, run:

uv run agent-memory-demo inspect-db

This starts a temporary Oracle container, seeds deterministic companion data, prints table counts, JSON case state, and graph paths, then tears the container down.

For hands-on SQL inspection, keep an interactive demo session open in one terminal:

uv run agent-memory-demo interactive

Wait for output like:

Started Oracle demo database at localhost:32838/FREEPDB1
Seeded companion relational, JSON, graph, and policy data.
Interactive Oracle AI Agent Memory demo. Type 'quit' to exit.
you>:

Leave that prompt open. The Oracle container is command-scoped and is removed when the command exits, so inspect the database before typing quit.

To populate managed memory rows during the interactive run, ask one prompt before you inspect, for example:

For user_id=user_alex and agent_id=support_agent, inspect memory tables and tell me what you can see in one sentence.

In a second terminal, connect with SQLcl, SQL*Plus, or another Oracle SQL tool:

sql agent_memory_demo/AgentMemoryDemo1@localhost:32838/FREEPDB1

Replace 32838 with the port printed by your run.

Useful inspection queries:

SELECT table_name
FROM user_tables
WHERE table_name LIKE 'OAM_DEMO%'
ORDER BY table_name;

SELECT table_name, column_name, data_type
FROM user_tab_columns
WHERE table_name LIKE 'OAM_DEMO%'
ORDER BY table_name, column_id;

SELECT index_name, table_name, column_name
FROM user_ind_columns
WHERE index_name LIKE 'OAM_DEMO_APP_GRAPH_EDGE%'
ORDER BY index_name, column_position;

SELECT case_id,
       title,
       json_value(state_json, '$.status') AS status,
       json_value(state_json, '$.next_action') AS next_action,
       json_value(state_json, '$.escalation_ready') AS escalation_ready
FROM OAM_DEMO_APP_CASE
ORDER BY case_id;

SELECT vertex_id, vertex_type, label
FROM OAM_DEMO_APP_GRAPH_VERTEX
ORDER BY vertex_type, vertex_id;

SELECT source_vertex_id, relationship_type, target_vertex_id
FROM OAM_DEMO_APP_GRAPH_EDGE
ORDER BY edge_id;

SELECT object_name, object_type
FROM user_objects
WHERE object_name = 'OAM_DEMO_APP_PROPERTY_GRAPH';

SELECT *
FROM OAM_DEMO_MEMORY
FETCH FIRST 5 ROWS ONLY;

SELECT *
FROM OAM_DEMO_RECORD_CHUNKS
FETCH FIRST 5 ROWS ONLY;

SELECT column_name, data_type
FROM user_tab_columns
WHERE table_name = 'OAM_DEMO_RECORD_CHUNKS'
  AND data_type = 'VECTOR';

SELECT index_name, index_type
FROM user_indexes
WHERE table_name = 'OAM_DEMO_RECORD_CHUNKS'
ORDER BY index_name;

If you do not have a SQL client installed, use the project oracledb dependency from a second terminal:

DEMO_DSN=localhost:32838/FREEPDB1 uv run python - <<'PY'
import os
import oracledb

connection = oracledb.connect(
    user="agent_memory_demo",
    password="AgentMemoryDemo1",
    dsn=os.environ["DEMO_DSN"],
)

with connection.cursor() as cursor:
    cursor.execute("""
        SELECT table_name
        FROM user_tables
        WHERE table_name LIKE 'OAM_DEMO%'
        ORDER BY table_name
    """)
    print("Tables:")
    for (table_name,) in cursor:
        print(f"- {table_name}")

    cursor.execute("""
        SELECT case_id,
               json_value(state_json, '$.status') AS status,
               json_value(state_json, '$.next_action') AS next_action
        FROM OAM_DEMO_APP_CASE
        ORDER BY case_id
    """)
    print("\nSupport case state:")
    for row in cursor:
        print(row)

connection.close()
PY

Troubleshooting

• Missing OpenAI key: copy .env.example to .env and set OPENAI_API_KEY.
• Docker unavailable: start Docker and rerun the command.
• Missing testcontainers Oracle support: run uv sync; the project depends on testcontainers[oracle].
• Slow Oracle startup: keep the default slim-faststart image, or set ORACLE_FREE_IMAGE to another gvenzl/oracle-free faststart tag.
• Image unavailable: set ORACLE_FREE_IMAGE to a reachable Oracle Free image tag.
• Schema reset concerns: all app-owned objects use the OAM_DEMO_APP_ prefix, and managed Agent Memory objects use OAM_DEMO_.

Development

Run the local test suite:

uv run python -m unittest discover tests

Most tests use fakes and do not start Docker or call OpenAI.