chore: import upstream snapshot with attribution

examples/showcases/oracle-agent-memory/db/Dockerfile

@@ -0,0 +1,31 @@
+# Custom Oracle AI Database image for Railway (Option B — self-host).
+#
+# It is the freely-pullable Oracle Database Free image with the `cookbook` user
+# baked in, so the database comes up ready with no manual setup step.
+#
+# Build + push to a PRIVATE registry ONLY — re-publishing Oracle's image
+# publicly violates the Oracle license. See build-and-push.sh.
+#
+# :latest-lite is the smaller Free variant (faster pulls / less disk on Railway)
+# and still includes AI Vector Search. Switch to :latest if you hit a missing
+# feature.
+FROM container-registry.oracle.com/database/free:latest-lite
+
+# Admin (SYS / SYSTEM / PDBADMIN) password — matches the local docker-compose default.
+ENV ORACLE_PWD=cookbook_admin_pw
+
+# Startup scripts (run on every container start, alphabetical order). We use the
+# *startup* hook rather than the *setup* hook: the Free image does NOT reliably
+# execute setup/ scripts (see the note in db/init/01-create-user.sql), and our SQL
+# is idempotent, so running it each boot is safe and robust. Baking it in (vs a
+# volume mount) also avoids the mount-timing race the local compose hit.
+#
+# 00 registers FREEPDB1 with the TCP listener on the container's IPv4 address so the
+#    agent can reach it over Railway's dual-stack private network (Railway fix — see
+#    the file header). A shell script (not SQL) because it must read the IPv4 from
+#    `hostname -I`; UTL_INADDR only yields the IPv6 address. No exec bit / chmod: the
+#    image runs as a non-root user (chmod during build is denied), and the startup
+#    hook *sources* non-executable .sh files — the script is written to be source-safe.
+# 01 creates the `cookbook` application user (idempotent).
+COPY init/00-register-listener.sh /opt/oracle/scripts/startup/00-register-listener.sh
+COPY init/01-create-user.sql /opt/oracle/scripts/startup/01-create-user.sql

examples/showcases/oracle-agent-memory/db/build-and-push.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# Build the custom Oracle DB image and push it to a PRIVATE registry for Railway.
+#
+# One-time prerequisites (you):
+#   1. Accept the image license at https://container-registry.oracle.com
+#      (Database -> free), signed in with your Oracle SSO account.
+#   2. docker login container-registry.oracle.com        # Oracle SSO
+#   3. docker login ghcr.io -u <github-username>          # GitHub PAT w/ write:packages
+#
+# Keep the target repo PRIVATE — re-publishing Oracle's image violates the license.
+set -euo pipefail
+
+# Set IMAGE, or replace OWNER with your own PRIVATE GHCR namespace before running.
+IMAGE="${IMAGE:-ghcr.io/OWNER/oracle-agent-memory-db:latest}"
+
+cd "$(dirname "$0")"   # db/ — build context includes init/
+
+echo "Building $IMAGE ..."
+docker build -t "$IMAGE" .
+
+echo "Pushing $IMAGE ..."
+docker push "$IMAGE"
+
+cat <<EOF
+
+Done: $IMAGE  (keep this repo PRIVATE — Oracle license).
+
+In Railway, create the 'oracle-db' service from it:
+  - Source:    Docker image -> $IMAGE   (add GHCR pull credentials if private)
+  - Volume:    mount at /opt/oracle/oradata
+  - Resources: >= 2 GB RAM
+  - Wait for "DATABASE IS READY TO USE" in the logs before deploying the agent.
+EOF

examples/showcases/oracle-agent-memory/db/init/00-register-listener.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# Railway remote-access fix (ORA-12514 / DPY-6001 "FREEPDB1 not registered").
+#
+# Railway's private network is dual-stack. The agent connects to the database over
+# IPv4 (10.x), but the DB's primary address -- what UTL_INADDR.GET_HOST_ADDRESS
+# returns -- is IPv6 (fd12:...). Registering the listener service on the IPv6 address
+# therefore leaves the IPv4-connecting agent with ORA-12514. This script pins
+# LOCAL_LISTENER to the container's own IPv4 address so PMON publishes both FREE (CDB)
+# and FREEPDB1 (PDB) to the TCP listener on the exact endpoint the agent reaches.
+#
+# Runs on every container boot (startup hook). SCOPE=MEMORY -- re-applied each boot.
+# The echoed IP + sqlplus output let the deploy logs confirm the fix applied, and on
+# which address, without needing shell access to the running container.
+#
+# Written to be safe whether the startup runner executes or sources it: no `set -e`
+# and no `exit` (which would abort the runner / skip 01-create-user.sql).
+
+IP4="$(hostname -I 2>/dev/null | tr ' ' '\n' | grep -E '^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$' | grep -vE '^127\.' | head -1)"
+
+if [ -z "$IP4" ]; then
+  echo "[register-listener] no non-loopback IPv4 found (hostname -I: $(hostname -I 2>/dev/null)); leaving LOCAL_LISTENER at default"
+else
+  echo "[register-listener] registering services on IPv4 ${IP4}:1521"
+  SQLPLUS="${ORACLE_HOME:+${ORACLE_HOME}/bin/}sqlplus"
+  "$SQLPLUS" -s "/ as sysdba" <<SQL
+WHENEVER SQLERROR CONTINUE
+ALTER SESSION SET CONTAINER = CDB\$ROOT;
+ALTER SYSTEM SET LOCAL_LISTENER='(ADDRESS=(PROTOCOL=TCP)(HOST=${IP4})(PORT=1521))' SCOPE=MEMORY;
+ALTER SYSTEM REGISTER;
+EXIT
+SQL
+  echo "[register-listener] done (IPv4 ${IP4})"
+fi

examples/showcases/oracle-agent-memory/db/init/01-create-user.sql

@@ -0,0 +1,88 @@
+-- Creates the `cookbook` application user inside the FREEPDB1 pluggable database
+-- with the privileges oracleagentmemory needs (tables + AI Vector Search), and a
+-- dedicated ASSM tablespace as its DEFAULT.
+--
+-- WHY THE ASSM TABLESPACE: oracleagentmemory creates tables with native JSON columns
+-- and a VECTOR column + HNSW vector index. Those segments are SecureFile LOB/BLOBs,
+-- which Oracle forbids in a Manual Segment Space Management (MSSM) tablespace
+-- (ORA-43853). On the Free `:latest-lite` image FREEPDB1 has NO USERS tablespace and
+-- its default permanent tablespace is SYSTEM (MSSM), so a user with no DEFAULT
+-- TABLESPACE lands on SYSTEM and the first JSON table fails. We therefore create an
+-- ASSM tablespace (cookbook_ts) and make it the user's default.
+--
+-- Idempotent — safe to run on every container boot (startup hook). Self-heals ONLY
+-- the genuinely broken case: a `cookbook` user stranded on the SYSTEM tablespace
+-- (MSSM), which is FREEPDB1's default permanent tablespace on :latest-lite and is what
+-- raises ORA-43853. Such a user is dropped (CASCADE) and recreated on cookbook_ts.
+-- DROP USER CASCADE is the correct self-heal because Oracle DDL auto-commits: a prior
+-- failed run can leave non-JSON tables (schema_meta, actor_profile) stranded in SYSTEM
+-- with empty metadata, and oracleagentmemory's 'create_if_necessary' policy will NOT
+-- recover from that — it raises a metadata-validation error instead of recreating into
+-- the new tablespace. CASCADE removes those stranded objects regardless of tablespace.
+--
+-- A user already on a working ASSM tablespace (e.g. USERS on the local :latest image)
+-- is LEFT UNTOUCHED, so re-running stays non-destructive on the documented local flow.
+-- The self-heal drop assumes a fresh boot with no live `cookbook` session (true for the
+-- ephemeral, no-volume demo: the DB is recreated each restart). Using a persisted volume
+-- would need session-disconnect handling before the drop (the agent reconnects as soon
+-- as the listener is up) — out of scope while the demo runs volume-less.
+ALTER SESSION SET CONTAINER = FREEPDB1;
+
+SET SERVEROUTPUT ON
+DECLARE
+  ts_count    INTEGER;
+  user_count  INTEGER;
+  default_ts  VARCHAR2(128);
+BEGIN
+  -- 1) Dedicated ASSM tablespace (guarded: CREATE TABLESPACE is NOT idempotent and
+  --    raises ORA-01543 if it already exists; REUSE only protects the datafile, not
+  --    the tablespace metadata). The datafile path is the verified PDB datafile dir
+  --    for the Free image (ORACLE_SID/db_name = FREE; OMF is off so an explicit path
+  --    is required). REUSE re-adopts an orphaned datafile left on the persisted volume.
+  SELECT COUNT(*) INTO ts_count
+    FROM dba_tablespaces
+   WHERE tablespace_name = 'COOKBOOK_TS';
+  IF ts_count = 0 THEN
+    EXECUTE IMMEDIATE
+      'CREATE TABLESPACE cookbook_ts ' ||
+      'DATAFILE ''/opt/oracle/oradata/FREE/FREEPDB1/cookbook_ts01.dbf'' ' ||
+      'SIZE 256M REUSE AUTOEXTEND ON NEXT 64M MAXSIZE 2G ' ||
+      'EXTENT MANAGEMENT LOCAL SEGMENT SPACE MANAGEMENT AUTO';
+    DBMS_OUTPUT.PUT_LINE('cookbook_ts tablespace created (ASSM)');
+  ELSE
+    DBMS_OUTPUT.PUT_LINE('cookbook_ts tablespace already exists - skipping');
+  END IF;
+
+  -- 2) Self-heal ONLY a user stranded on SYSTEM (MSSM) — the sole default that causes
+  --    ORA-43853 (only FREEPDB1's default on :latest-lite). Drop + recreate it on the
+  --    ASSM tablespace. A user already on a working ASSM tablespace (e.g. USERS on the
+  --    local :latest image, or cookbook_ts itself) is left untouched, so re-running is
+  --    non-destructive there. dba_users.default_tablespace is stored uppercase.
+  SELECT COUNT(*) INTO user_count
+    FROM dba_users WHERE username = 'COOKBOOK';
+
+  IF user_count > 0 THEN
+    SELECT default_tablespace INTO default_ts
+      FROM dba_users WHERE username = 'COOKBOOK';
+    IF default_ts = 'SYSTEM' THEN
+      DBMS_OUTPUT.PUT_LINE('cookbook is on SYSTEM (MSSM) - dropping to self-heal onto cookbook_ts');
+      EXECUTE IMMEDIATE 'DROP USER cookbook CASCADE';
+      user_count := 0;
+    ELSE
+      DBMS_OUTPUT.PUT_LINE('cookbook user default tablespace is ' || default_ts ||
+                           ' (ASSM) - leaving as-is');
+    END IF;
+  END IF;
+
+  IF user_count = 0 THEN
+    EXECUTE IMMEDIATE
+      'CREATE USER cookbook IDENTIFIED BY "cookbook_pw" ' ||
+      'DEFAULT TABLESPACE cookbook_ts TEMPORARY TABLESPACE temp';
+    EXECUTE IMMEDIATE 'GRANT DB_DEVELOPER_ROLE TO cookbook';
+    -- GRANT UNLIMITED TABLESPACE covers quota on every tablespace (incl. cookbook_ts),
+    -- so no separate QUOTA clause is needed; one privilege, no redundancy.
+    EXECUTE IMMEDIATE 'GRANT UNLIMITED TABLESPACE TO cookbook';
+    DBMS_OUTPUT.PUT_LINE('cookbook user created (DEFAULT TABLESPACE cookbook_ts)');
+  END IF;
+END;
+/

examples/showcases/oracle-agent-memory/db/setup-db.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+# Create the `cookbook` database user (idempotent).
+#
+# The Oracle Database Free image does not reliably auto-run scripts mounted into
+# /opt/oracle/scripts/setup, so we run the init SQL explicitly against the running
+# container. Run this once after `docker compose up -d` reports the DB ready
+# ("DATABASE IS READY TO USE"). Safe to re-run.
+set -euo pipefail
+
+CONTAINER="${ORACLE_CONTAINER:-oracle-cookbook-db}"
+
+if ! docker ps --format '{{.Names}}' | grep -qx "$CONTAINER"; then
+  echo "Error: container '$CONTAINER' is not running. Start it with: docker compose up -d" >&2
+  exit 1
+fi
+
+echo "Ensuring the 'cookbook' user exists in FREEPDB1..."
+docker exec "$CONTAINER" bash -lc \
+  'echo exit | "$ORACLE_HOME"/bin/sqlplus -s "/ as sysdba" @/opt/oracle/scripts/setup/01-create-user.sql'
+echo "Done — the 'cookbook' user is ready."