chore: import upstream snapshot with attribution

examples/showcases/oracle-agent-memory/agent/.dockerignore

@@ -0,0 +1,7 @@
+# Keep the local virtualenv, caches, and secrets out of the build context.
+.venv/
+__pycache__/
+**/__pycache__/
+*.pyc
+.env
+.env.*

examples/showcases/oracle-agent-memory/agent/.env.example

@@ -0,0 +1,12 @@
+# ── LLM / embedding provider (litellm-backed; defaults use OpenAI) ────────────
+OPENAI_API_KEY=sk-...
+CHAT_MODEL=gpt-5.4-mini            # model the Agent Spec agent answers with
+MEMORY_LLM_MODEL=gpt-5.4-mini      # model oracleagentmemory uses to extract memories
+EMBEDDING_MODEL=text-embedding-3-small
+
+# ── Oracle AI Database (root docker-compose) ───────────
+ORACLE_DB_USER=cookbook
+ORACLE_DB_PASSWORD=cookbook_pw
+ORACLE_DB_DSN=localhost:1521/FREEPDB1
+
+LANGGRAPH_CHECKPOINTER=memory     # set to "oracle" for durable LangGraph graph state in Oracle

examples/showcases/oracle-agent-memory/agent/.python-version

@@ -0,0 +1 @@
+3.12

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

@@ -0,0 +1,27 @@
+# Agent service image (Railway). Python 3.12 is required — oracleagentmemory
+# ships a cp312-only wheel.
+FROM python:3.12-slim
+
+# git: the ag_ui_agentspec adapter installs from the ag-ui git repo (see pyproject).
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends git ca-certificates \
+ && rm -rf /var/lib/apt/lists/*
+
+# uv — the project's package manager.
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /usr/local/bin/
+# Use the image's system Python 3.12 (don't fetch a managed interpreter).
+ENV UV_PYTHON_PREFERENCE=only-system UV_PYTHON_DOWNLOADS=never
+
+WORKDIR /app
+
+# Install dependencies from the lockfile first (cached layer). The project is not
+# a package (tool.uv.package = false), so only the deps are installed.
+COPY pyproject.toml uv.lock ./
+RUN uv sync --frozen --no-install-project
+
+# App code.
+COPY . .
+
+EXPOSE 8000
+# Bind Railway's $PORT (8000 locally). --no-sync: deps are already installed.
+CMD ["sh", "-c", "uv run --no-sync uvicorn concierge.server:app --host 0.0.0.0 --port ${PORT:-8000}"]

examples/showcases/oracle-agent-memory/agent/concierge/agent.py

@@ -0,0 +1,52 @@
+"""Declaratively define the travel-concierge agent in Agent Spec and serialize it."""
+
+from __future__ import annotations
+
+import os
+
+from pyagentspec.agent import Agent
+from pyagentspec.llms import OpenAiCompatibleConfig
+from pyagentspec.serialization import AgentSpecSerializer
+
+from .tools import TOOLS
+
+SYSTEM_PROMPT = """You are a personal flight concierge with long-term memory.
+
+Start every conversation by calling recall_memory to retrieve the traveler's durable
+preferences — home airport, seat preference (e.g. aisle), meal preference (e.g.
+vegetarian), and favorite airlines or destinations. Weave these in naturally; never
+say "according to my memory" or reveal that you looked something up.
+
+Use search_flights to find available flights for the requested destination. Present
+the results clearly, highlighting options that best honor the traveler's recalled
+preferences (e.g. nonstop if they prefer it, aisle seat availability, vegetarian meal
+on request, preferred airline or home airport as origin).
+
+When the traveler has chosen a flight and wants to book it, call book_flight with the
+chosen flight's id (e.g. 'AMS-001'). The traveler will confirm the booking in the UI
+before it is finalized — do not ask them to confirm again in chat."""
+
+
+def build_agent() -> Agent:
+    # Do NOT set api_key here: AgentSpecSerializer treats it as a SensitiveField and
+    # disaggregates it out of the serialized JSON, which then fails to load without a
+    # components_registry ("references ... missing ... api_key"). Leave it unset — the
+    # LangGraph ChatOpenAI reads OPENAI_API_KEY from the environment (load_dotenv in
+    # server.py puts it there).
+    llm = OpenAiCompatibleConfig(
+        name="concierge_llm",
+        model_id=os.getenv("CHAT_MODEL", "gpt-5.4-mini"),
+        url=os.getenv("OPENAI_BASE_URL", "https://api.openai.com/v1"),
+    )
+    return Agent(
+        name="travel_concierge",
+        llm_config=llm,
+        system_prompt=SYSTEM_PROMPT,
+        tools=TOOLS,
+        human_in_the_loop=True,
+    )
+
+
+def build_agent_json() -> str:
+    """Return the Agent Spec JSON string the adapter loads."""
+    return AgentSpecSerializer().to_json(build_agent())

examples/showcases/oracle-agent-memory/agent/concierge/checkpointer.py

@@ -0,0 +1,106 @@
+"""Flag-gated LangGraph checkpointer for durable Oracle graph state.
+
+Resolves the LangGraph checkpointer based on the ``LANGGRAPH_CHECKPOINTER``
+environment variable.  When set to ``oracle``, builds a dedicated async Oracle
+connection pool and an ``AsyncOracleSaver`` (durable graph-state persistence
+that complements OracleAgentMemory for conversation history).  Any other value
+— or the default when the variable is absent — falls back to an in-memory
+``MemorySaver`` so the agent works without a database.
+
+Usage::
+
+    await init_checkpointer()          # call once at startup
+    checkpointer = resolve_checkpointer()  # call per LangGraph graph build
+    ...
+    await close_checkpointer()         # call once at shutdown
+"""
+
+from __future__ import annotations
+
+import os
+
+import oracledb
+from langgraph.checkpoint.memory import MemorySaver
+from langgraph_oracledb.checkpoint.oracle import AsyncOracleSaver
+
+# ---------------------------------------------------------------------------
+# Module-level globals – populated by init_checkpointer()
+# ---------------------------------------------------------------------------
+_pool = None
+_saver = None
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _require(name: str) -> str:
+    value = os.getenv(name)
+    if not value:
+        raise RuntimeError(
+            f"Missing required environment variable {name!r}. "
+            "Copy agent/.env.example to agent/.env and fill it in."
+        )
+    return value
+
+
+def _flag() -> str:
+    return os.getenv("LANGGRAPH_CHECKPOINTER", "memory").lower()
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+async def init_checkpointer() -> None:
+    """Initialise the Oracle async pool + AsyncOracleSaver when the flag is set.
+
+    Safe to call at startup unconditionally — exits immediately when the flag
+    is not ``oracle``.  On any failure the module degrades gracefully to the
+    in-memory saver rather than crashing the server.
+    """
+    global _pool, _saver
+
+    if _flag() != "oracle":
+        return
+
+    try:
+        _pool = oracledb.create_pool_async(
+            user=_require("ORACLE_DB_USER"),
+            password=_require("ORACLE_DB_PASSWORD"),
+            dsn=_require("ORACLE_DB_DSN"),
+            min=1,
+            max=4,
+            increment=1,
+        )
+        _saver = AsyncOracleSaver(_pool)
+        await _saver.setup()
+    except Exception as exc:
+        print(f"[checkpointer] warning: Oracle checkpointer init failed — degrading to MemorySaver ({exc})")
+        _pool = None
+        _saver = None
+
+
+async def close_checkpointer() -> None:
+    """Close the async Oracle pool and reset the module globals.
+
+    Safe to call unconditionally at shutdown (no-op when the pool was never
+    opened or already closed).
+    """
+    global _pool, _saver
+
+    if _pool is not None:
+        await _pool.close()
+        _pool = None
+        _saver = None
+
+
+def resolve_checkpointer():
+    """Return the active checkpointer for use in a LangGraph graph build.
+
+    Returns the ``AsyncOracleSaver`` when the flag is ``oracle`` AND the saver
+    was successfully initialised; otherwise returns a fresh ``MemorySaver()``.
+    """
+    if _flag() == "oracle" and _saver is not None:
+        return _saver
+    return MemorySaver()

examples/showcases/oracle-agent-memory/agent/concierge/memory.py

@@ -0,0 +1,45 @@
+"""Build and cache the OracleAgentMemory client."""
+
+from __future__ import annotations
+
+import functools
+import os
+
+import oracledb
+from oracleagentmemory.core import OracleAgentMemory
+from oracleagentmemory.core.embedders.embedder import Embedder
+from oracleagentmemory.core.llms.llm import Llm
+
+
+def _require(name: str) -> str:
+    value = os.getenv(name)
+    if not value:
+        raise RuntimeError(
+            f"Missing required environment variable {name!r}. "
+            "Copy agent/.env.example to agent/.env and fill it in."
+        )
+    return value
+
+
+@functools.lru_cache(maxsize=1)
+def get_memory() -> OracleAgentMemory:
+    """Return a process-wide singleton memory client (lazily constructed)."""
+    pool = oracledb.create_pool(
+        user=_require("ORACLE_DB_USER"),
+        password=_require("ORACLE_DB_PASSWORD"),
+        dsn=_require("ORACLE_DB_DSN"),  # e.g. "localhost:1521/FREEPDB1"
+        min=1,
+        max=4,
+        increment=1,
+    )
+    embedder = Embedder(model=os.getenv("EMBEDDING_MODEL", "text-embedding-3-small"))
+    llm = Llm(model=os.getenv("MEMORY_LLM_MODEL", "gpt-5.4-mini"))
+    # schema_policy="create_if_necessary" provisions the memory tables on first
+    # run (the cookbook DB user has DB_DEVELOPER_ROLE). Without it, OracleAgentMemory
+    # errors on a fresh database with "Managed DB schema is missing required objects".
+    return OracleAgentMemory(
+        connection=pool,
+        embedder=embedder,
+        llm=llm,
+        schema_policy="create_if_necessary",
+    )

examples/showcases/oracle-agent-memory/agent/concierge/reconcile.py

@@ -0,0 +1,90 @@
+"""LLM-driven supersession for durable memories.
+
+Oracle Agent Memory *accumulates* extracted facts; it doesn't retract an old one
+when a contradicting newer one arrives. So after a traveler changes a preference
+("I now fly from Cebu" after an earlier "I fly from SFO"), both coexist and recall
+keeps surfacing the stale value. This pass asks the memory LLM to identify
+outdated/duplicate durable facts and deletes them, so the most recent value wins on
+the next recall. It runs in the background after each turn and degrades to a no-op
+on any error (we never delete unless the LLM names ids from the candidate set).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+
+from openai import OpenAI
+from oracleagentmemory.apis.searchscope import SearchScope
+
+from .memory import get_memory
+from .tools import DURABLE_RECORD_TYPES
+
+_SYSTEM_PROMPT = """You curate a traveler's durable travel preferences stored as facts.
+You are given a JSON list of facts, each with an "id", a "when" timestamp, and "text".
+
+Mark a fact for deletion when:
+- Two or more facts describe the SAME attribute (e.g. home/departure airport, seat
+  preference, meal preference) with the same OR conflicting values — keep ONLY the most
+  recent (latest "when") and delete the older ones.
+- A fact is a near-duplicate of another — keep the most recent, delete the rest.
+
+Never delete facts about DISTINCT attributes. When in doubt, keep it.
+Return strict JSON: {"delete_ids": ["<id>", ...]}. Use only ids present in the input."""
+
+
+def _client() -> OpenAI:
+    return OpenAI(
+        api_key=os.environ["OPENAI_API_KEY"],
+        base_url=os.getenv("OPENAI_BASE_URL", "https://api.openai.com/v1"),
+    )
+
+
+def reconcile_durable_memories(user_id: str) -> int:
+    """Delete superseded / duplicate durable memories for ``user_id``.
+
+    Returns the number of records deleted (0 on no-op or any failure).
+    """
+    memory = get_memory()
+    results = memory.search(
+        query="traveler durable preferences: home airport, seat, meal, airlines, destinations",
+        scope=SearchScope(user_id=user_id),
+        record_types=DURABLE_RECORD_TYPES,
+        max_results=50,
+    )
+
+    facts = []
+    for r in results:
+        rid = getattr(r, "id", None)
+        content = (getattr(r, "content", "") or "").strip()
+        if rid and content:
+            facts.append({"id": rid, "when": str(getattr(r, "timestamp", "")), "text": content})
+
+    if len(facts) < 2:
+        return 0
+
+    valid_ids = {f["id"] for f in facts}
+    try:
+        resp = _client().chat.completions.create(
+            model=os.getenv("MEMORY_LLM_MODEL", "gpt-5.4-mini"),
+            response_format={"type": "json_object"},
+            messages=[
+                {"role": "system", "content": _SYSTEM_PROMPT},
+                {"role": "user", "content": json.dumps(facts, ensure_ascii=False)},
+            ],
+        )
+        data = json.loads(resp.choices[0].message.content or "{}")
+        delete_ids = [i for i in data.get("delete_ids", []) if i in valid_ids]
+    except Exception as exc:  # never let reconciliation break persistence
+        print(f"[reconcile] skipped (LLM/parse failed: {exc!r})")
+        return 0
+
+    deleted = 0
+    for rid in delete_ids:
+        try:
+            deleted += memory.delete_memory(rid)
+        except Exception as exc:
+            print(f"[reconcile] delete {rid} failed: {exc!r}")
+    if deleted:
+        print(f"[reconcile] superseded {deleted} stale/duplicate memories for {user_id}")
+    return deleted

examples/showcases/oracle-agent-memory/agent/concierge/server.py

@@ -0,0 +1,338 @@
+"""FastAPI server: Agent Spec agent on LangGraph over AG-UI, + durable memory.
+
+We hand-roll the AG-UI streaming route (copied from the adapter's thin
+`add_agentspec_fastapi_endpoint`) so we can persist each exchange to Oracle
+Agent Memory — the adapter exposes no post-run hook. Persistence runs as a
+background task once the run finishes (off the SSE critical path, so the stream
+closes at RUN_FINISHED); it is fully server-side, and the frontend just streams
+from /run.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import html
+from contextlib import asynccontextmanager
+
+from ag_ui.core import EventType, RunAgentInput, RunErrorEvent
+from ag_ui.encoder import EventEncoder
+from ag_ui_agentspec.agent import AgentSpecAgent
+from ag_ui_agentspec.agentspec_tracing_exporter import EVENT_QUEUE
+from dotenv import load_dotenv
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import StreamingResponse
+
+from .agent import build_agent_json
+from .memory import get_memory
+from .reconcile import reconcile_durable_memories
+from .tools import DEMO_USER_ID, TOOL_REGISTRY
+
+load_dotenv()
+
+
+# ── Multi-turn fix (upstream adapter workaround) ──────────────────────────────
+# The ag_ui_agentspec LangGraph runner checkpoints history per thread_id and, on
+# each turn, tries to append only the client messages whose ids aren't already in
+# the checkpoint (filter_only_new_messages). But CopilotKit re-sends the *full*
+# history with ids that never match the checkpoint's, so a second copy of the
+# assistant(tool_calls)/tool block gets appended; OpenAI then rejects the malformed
+# sequence on the next turn (400: "a message with role 'tool' must be a response to
+# a preceeding message with 'tool_calls'"), breaking every follow-up after a server
+# tool runs. See docs/known-issues/agentspec-multiturn-toolcall-correlation.md.
+#
+# Since the client already sends the full, valid history each turn, we replace the
+# adapter's incremental merge with a full-history *replace*: clear the checkpoint's
+# messages (RemoveMessage) and use the client's history verbatim. Drop this once the
+# upstream adapter records ToolExecutionRequests so the ids correlate.
+from langchain_core.messages import RemoveMessage  # noqa: E402
+from langgraph.graph.message import REMOVE_ALL_MESSAGES  # noqa: E402
+import ag_ui_agentspec.runtimes.langgraph_runner as _lg_runner  # noqa: E402
+
+
+def _repair_dangling_tool_calls(messages: list[dict]) -> list[dict]:
+    """Synthesize a tool result for any assistant tool_call that has no response.
+
+    book_flight is a client-side HITL tool: calling it interrupts the run and emits
+    an assistant message with a tool_call, then waits for the UI to return a result
+    when the traveler clicks Confirm/Cancel. If they instead send another chat
+    message, that tool_call is left unanswered — and because we forward the client's
+    full history verbatim, OpenAI rejects the next turn (400: "tool_call_ids did not
+    have response messages"). This is the inverse of the duplicate-tool-block issue
+    the history replace already handles (see the comment above).
+
+    For each assistant tool_call with no real tool result, insert a synthetic
+    "not completed" tool result directly after the assistant message so the sequence
+    is valid and the model can answer the new question. In this app the only tool
+    that can dangle is the book_flight HITL — server tools resolve within the run —
+    so the synthetic content is phrased for that case.
+
+    Assumes CopilotKit's normal ordering, where a real tool result immediately
+    follows its assistant tool_calls message: this repairs *missing* results, not a
+    result that has been re-ordered away from its originating call.
+    """
+    # tool_call_ids that already have a REAL result somewhere in the history.
+    answered = {
+        m["tool_call_id"]
+        for m in messages
+        if m.get("role") == "tool" and m.get("tool_call_id")
+    }
+    repaired: list[dict] = []
+    for m in messages:
+        repaired.append(m)
+        if m.get("role") != "assistant" or not m.get("tool_calls"):
+            continue
+        # De-dupe within THIS message only — a second assistant message carrying the
+        # same unanswered id still needs its own result, so `answered` is never
+        # mutated here (mutating it was the original bug: it suppressed the repair the
+        # next occurrence needed).
+        synthesized: set[str] = set()
+        for tc in m["tool_calls"]:
+            tc_id = tc.get("id")
+            if not tc_id:
+                # Can't synthesize a result without an id; surface it rather than
+                # silently leave a dangling call that 400s on the next turn.
+                print("[history] warning: assistant tool_call has no id; cannot repair")
+                continue
+            if tc_id in answered or tc_id in synthesized:
+                continue
+            synthesized.add(tc_id)
+            name = (tc.get("function") or {}).get("name") or "the requested action"
+            repaired.append(
+                {
+                    "role": "tool",
+                    "tool_call_id": tc_id,
+                    "content": f"{name} was not completed — the traveler continued without confirming.",
+                }
+            )
+    return repaired
+
+
+async def _replace_history_with_client(_agent, _thread_id, input_messages):
+    """Replace the checkpoint's messages with the client's full history each turn,
+    repairing any dangling tool_call (e.g. an abandoned book_flight HITL) first."""
+    if not input_messages:
+        return input_messages
+    return [RemoveMessage(id=REMOVE_ALL_MESSAGES), *_repair_dangling_tool_calls(input_messages)]
+
+
+_lg_runner.filter_only_new_messages = _replace_history_with_client
+
+# ── Oracle checkpointer injection (Plan §3, Option A) ─────────────────────────
+# ag_ui_agentspec's load_agent_spec hardcodes checkpointer=MemorySaver(); we
+# replace it so the LangGraph graph is compiled with our flag-gated checkpointer
+# (AsyncOracleSaver when LANGGRAPH_CHECKPOINTER=oracle, else MemorySaver). The
+# underlying pyagentspec AgentSpecLoader already accepts a checkpointer; only the
+# convenience wrapper needed patching. Drop this once the upstream adapter takes a
+# checkpointer param (Plan §3, Option B). AgentSpecAgent.__init__ resolves the name
+# from ag_ui_agentspec.agent, so we rebind both module namespaces.
+import ag_ui_agentspec.agent as _agent_mod  # noqa: E402
+import ag_ui_agentspec.agentspecloader as _asl_mod  # noqa: E402
+from pyagentspec.adapters.langgraph import AgentSpecLoader as _LGLoader  # noqa: E402
+
+from .checkpointer import resolve_checkpointer, init_checkpointer, close_checkpointer  # noqa: E402
+
+_orig_load_agent_spec = _agent_mod.load_agent_spec
+
+
+def _load_agent_spec_with_checkpointer(
+    runtime, agent_spec_json, tool_registry=None, components_registry=None
+):
+    if runtime != "langgraph":
+        return _orig_load_agent_spec(
+            runtime, agent_spec_json, tool_registry, components_registry
+        )
+    return _LGLoader(
+        tool_registry=tool_registry, checkpointer=resolve_checkpointer()
+    ).load_json(agent_spec_json, components_registry)
+
+
+_agent_mod.load_agent_spec = _load_agent_spec_with_checkpointer
+_asl_mod.load_agent_spec = _load_agent_spec_with_checkpointer
+
+
+@asynccontextmanager
+async def _lifespan(_app: FastAPI):
+    # Build the Oracle checkpointer (if LANGGRAPH_CHECKPOINTER=oracle) before the
+    # lazy agent build so resolve_checkpointer() sees an initialised saver. No-op
+    # under the default `memory` flag.
+    await init_checkpointer()
+    try:
+        yield
+    finally:
+        # Drain in-flight background persists on shutdown so a graceful stop doesn't
+        # drop the last turn's memory write. Loop rather than a single gather: a
+        # request finishing during the drain can add a task after the snapshot, so
+        # re-check until the set is empty. Persists are serialized (one at a time).
+        while _PERSIST_TASKS:
+            await asyncio.gather(*list(_PERSIST_TASKS), return_exceptions=True)
+        await close_checkpointer()
+
+
+app = FastAPI(title="Oracle Concierge Agent", lifespan=_lifespan)
+app.add_middleware(
+    CORSMiddleware, allow_origins=["*"], allow_methods=["*"], allow_headers=["*"]
+)
+
+@functools.lru_cache(maxsize=1)
+def _get_agentspec_agent() -> AgentSpecAgent:
+    """Build the agent once, on first request. Construction eagerly resolves the
+    LLM (ChatOpenAI), which needs OPENAI_API_KEY, so we defer it out of import."""
+    return AgentSpecAgent(
+        build_agent_json(), runtime="langgraph", tool_registry=TOOL_REGISTRY
+    )
+
+
+@app.get("/health")
+async def health() -> dict[str, str]:
+    return {"status": "ok"}
+
+
+def _last_user_message(messages: list) -> str:
+    for message in reversed(messages):
+        if getattr(message, "role", None) == "user":
+            return getattr(message, "content", "") or ""
+    return ""
+
+
+def _clean_assistant_text(parts: list[str]) -> str:
+    """Assemble the streamed assistant deltas into the text we persist to memory.
+
+    The agentspec exporter HTML-escapes every TEXT_MESSAGE_CHUNK delta for safe
+    transport to the browser (agentspec_tracing_exporter._escape_html: & < > ->
+    &amp; &lt; &gt;). We must reverse that before persisting, or Oracle Agent
+    Memory stores corrupted facts like "fares &lt; $700" and recall/extraction
+    operate on the mangled text. Join first, then unescape, so an entity split
+    across two delta boundaries (e.g. "&l" + "t;") is still decoded correctly.
+    The streamed copy yielded to the client is untouched — only the persisted
+    copy is unescaped here.
+    """
+    return html.unescape("".join(parts))
+
+
+# Background persistence tasks are tracked here so the event loop keeps a strong
+# reference until each finishes — a bare fire-and-forget task can be garbage
+# collected mid-flight (see the asyncio.create_task docs).
+_PERSIST_TASKS: set[asyncio.Task] = set()
+# Serialize background persists: only one extraction + reconciliation runs at a
+# time. The old await made the client wait on stream-close before sending the
+# next turn, which serialized persists for free; now that the stream closes at
+# RUN_FINISHED, overlapping turns could otherwise run reconcile's read-modify-
+# write concurrently (racing on which durable fact "wins") and exhaust the small
+# Oracle connection pool. Background persists queue on this lock instead.
+_PERSIST_LOCK = asyncio.Lock()
+
+
+async def _persist_serialized(user_text: str, assistant_text: str) -> None:
+    async with _PERSIST_LOCK:
+        await asyncio.to_thread(_persist_sync, user_text, assistant_text)
+
+
+def _on_persist_done(task: asyncio.Task) -> None:
+    """Drop the task ref and surface any failure. The write happens off the
+    request path, so a silently-dropped task exception would make a lost write
+    invisible. _persist_sync swallows its own DB/LLM errors; this catches
+    cancellation (loop shutdown) and scheduling failures that would vanish."""
+    _PERSIST_TASKS.discard(task)
+    if task.cancelled():
+        print("[persist] warning: background persist cancelled before completing")
+        return
+    exc = task.exception()
+    if exc is not None:
+        print(f"[persist] warning: background persist task failed ({exc!r})")
+
+
+def _spawn_persist(user_text: str, assistant_text: str) -> None:
+    """Run persistence off the request's critical path.
+
+    _persist_sync makes two LLM calls (memory extraction + reconciliation) plus
+    DB writes — ~2-13s in practice. Awaiting it in the SSE generator's finally
+    held the HTTP stream open that whole time *after* RUN_FINISHED, so the client
+    (which ends its run/loading state on stream-close, not on RUN_FINISHED) showed
+    a multi-second lag once the reply had already finished. Spawning it as a
+    tracked, serialized background task lets the stream close at RUN_FINISHED; the
+    write still lands a few seconds later, well before a human starts the next turn.
+    """
+    task = asyncio.create_task(_persist_serialized(user_text, assistant_text))
+    _PERSIST_TASKS.add(task)
+    task.add_done_callback(_on_persist_done)
+
+
+def _persist_sync(user_text: str, assistant_text: str) -> None:
+    """Persist the exchange for memory extraction, then supersede stale facts.
+
+    Both turns are stored: extraction reliably distills durable facts from a full
+    user+assistant exchange, whereas a lone user turn often yields only a raw
+    "message" record and no extracted fact. The agent's echoes land as "message"
+    records too, but recall_memory filters those out (see tools.DURABLE_RECORD_TYPES),
+    so they never re-assert a stale preference. Reconciliation then deletes
+    outdated/duplicate *durable* facts so an updated preference wins on recall.
+    """
+    exchange: list[dict[str, str]] = []
+    if user_text:
+        exchange.append({"role": "user", "content": user_text})
+    if assistant_text:
+        exchange.append({"role": "assistant", "content": assistant_text})
+    if not exchange:
+        return
+    try:
+        memory = get_memory()
+        thread = memory.create_thread(user_id=DEMO_USER_ID)
+        thread.add_messages(exchange)  # triggers automatic memory extraction
+        # Delete outdated/duplicate durable facts so the newest preference wins on recall.
+        reconcile_durable_memories(DEMO_USER_ID)
+    except Exception as exc:  # persistence is best-effort; a DB blip must not 500 the run
+        # Mirror recall_memory's graceful degradation: the chat reply already streamed
+        # successfully, so swallow + log rather than raising out of the SSE generator's
+        # finally (which surfaced as "Exception in ASGI application" while the DB was down).
+        print(f"[persist] warning: memory persist failed, degrading gracefully ({exc})")
+
+
+@app.post("/run")
+async def run_endpoint(input_data: RunAgentInput, request: Request):
+    """Stream the Agent Spec run over AG-UI, then persist the turn in the background.
+
+    The event_generator mirrors the adapter's endpoint.py: a per-request queue is
+    set into EVENT_QUEUE, the run is spawned as a task, and events are drained to
+    SSE. We additionally collect the assistant's text deltas and, once the stream
+    closes, spawn persistence as a background task (off the critical path).
+    """
+    encoder = EventEncoder(accept=request.headers.get("accept"))
+    user_text = _last_user_message(input_data.messages)
+
+    async def event_generator():
+        queue: asyncio.Queue = asyncio.Queue()
+        token = EVENT_QUEUE.set(queue)
+        assistant_parts: list[str] = []
+
+        async def run_and_close():
+            try:
+                await _get_agentspec_agent().run(input_data)
+            except Exception as exc:  # surface failures to the client
+                queue.put_nowait(RunErrorEvent(message=repr(exc)))
+            finally:
+                queue.put_nowait(None)
+
+        try:
+            asyncio.create_task(run_and_close())
+            while True:
+                item = await queue.get()
+                if item is None:
+                    break
+                if item.type in (EventType.RUN_STARTED, EventType.RUN_FINISHED):
+                    item.thread_id = input_data.thread_id
+                    item.run_id = input_data.run_id
+                if item.type == EventType.TEXT_MESSAGE_CHUNK:
+                    assistant_parts.append(getattr(item, "delta", "") or "")
+                yield encoder.encode(item)
+        except Exception as exc:
+            yield encoder.encode(RunErrorEvent(message=str(exc)))
+        finally:
+            EVENT_QUEUE.reset(token)
+            # Persist off the critical path so the SSE stream closes at RUN_FINISHED
+            # instead of blocking on memory extraction + reconciliation. The write
+            # still lands shortly after, so the next session can recall it.
+            _spawn_persist(user_text, _clean_assistant_text(assistant_parts))
+
+    return StreamingResponse(event_generator(), media_type=encoder.get_content_type())

examples/showcases/oracle-agent-memory/agent/concierge/tools.py

@@ -0,0 +1,157 @@
+"""ServerTool and ClientTool implementations + their Agent Spec declarations and registry.
+
+- recall_memory:   durable, cross-session recall from Oracle Agent Memory (ServerTool).
+- search_flights:  mock flight-search tool by destination (ServerTool, canned options).
+- book_flight:     client-side booking tool — the UI handles confirmation (ClientTool, HITL).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+
+from oracleagentmemory.apis.searchscope import SearchScope
+from pyagentspec.property import Property
+from pyagentspec.tools import ServerTool, ClientTool
+
+from .memory import get_memory
+
+# The adapter drops forwarded_props, so a single-user cookbook defaults here.
+# To scope per real user, set this from a ContextVar populated by a FastAPI
+# dependency (e.g. an X-User-Id header). See server.py.
+DEMO_USER_ID = "demo-user"
+
+# ── Mock flight inventory (keeps the tool runnable without a travel API) ──────
+_FLIGHTS = [
+    {
+        "id": "AMS-001",
+        "airline": "KLM",
+        "flight_no": "KL606",
+        "origin": "SFO",
+        "destination": "Amsterdam (AMS)",
+        "depart": "2026-07-12T13:25",
+        "arrive": "2026-07-13T09:10",
+        "duration": "10h 45m",
+        "stops": 0,
+        "cabin": "Economy",
+        "price_usd": 740,
+        "notes": "Nonstop · aisle seats available · vegetarian meal on request",
+    },
+    {
+        "id": "AMS-002",
+        "airline": "United",
+        "flight_no": "UA950",
+        "origin": "SFO",
+        "destination": "Amsterdam (AMS)",
+        "depart": "2026-07-12T15:40",
+        "arrive": "2026-07-13T14:05",
+        "duration": "13h 25m",
+        "stops": 1,
+        "cabin": "Economy",
+        "price_usd": 612,
+        "notes": "1 stop (EWR) · vegetarian meal on request",
+    },
+    {
+        "id": "LIS-010",
+        "airline": "TAP Air Portugal",
+        "flight_no": "TP238",
+        "origin": "SFO",
+        "destination": "Lisbon (LIS)",
+        "depart": "2026-07-12T16:10",
+        "arrive": "2026-07-13T13:30",
+        "duration": "12h 20m",
+        "stops": 1,
+        "cabin": "Economy",
+        "price_usd": 690,
+        "notes": "1 stop (LIS) · ocean-view layover",
+    },
+    {
+        "id": "TYO-021",
+        "airline": "ANA",
+        "flight_no": "NH7",
+        "origin": "SFO",
+        "destination": "Tokyo (HND)",
+        "depart": "2026-07-12T11:00",
+        "arrive": "2026-07-13T15:35",
+        "duration": "11h 35m",
+        "stops": 0,
+        "cabin": "Economy",
+        "price_usd": 1480,
+        "notes": "Nonstop · aisle seats available · JR pass add-on",
+    },
+]
+
+
+# Durable record types worth recalling. Excludes "message" — the raw chat turns
+# (including the agent's own replies like "You usually fly out of SFO…"), which
+# otherwise dominate recall and re-assert stale preferences.
+DURABLE_RECORD_TYPES = ["preference", "memory", "fact", "guideline"]
+
+
+def _recall_sync(query: str) -> str:
+    try:
+        memory = get_memory()
+        results = memory.search(
+            query=query,
+            scope=SearchScope(user_id=DEMO_USER_ID),
+            record_types=DURABLE_RECORD_TYPES,
+            max_results=20,
+        )
+        contents: list[str] = []
+        seen: set[str] = set()
+        for r in results:
+            c = (r.content or "").strip()
+            if not c or c.lower() in seen:
+                continue
+            seen.add(c.lower())
+            contents.append(c)
+            if len(contents) >= 6:
+                break
+        return "\n".join(f"- {c}" for c in contents) if contents else "No relevant memories."
+    except Exception as exc:  # memory is an enhancement, not a hard dependency
+        print(f"[recall_memory] warning: memory search failed, degrading gracefully ({exc})")
+        return "No relevant memories."
+
+
+async def recall_memory(query: str) -> str:
+    """Recall the traveler's durable preferences relevant to `query`."""
+    return await asyncio.to_thread(_recall_sync, query)
+
+
+async def search_flights(destination: str) -> str:
+    """Return mock flight options matching `destination` (or all, if no match)."""
+    matches = [t for t in _FLIGHTS if destination.lower() in t["destination"].lower()]
+    return json.dumps(matches or _FLIGHTS)
+
+
+def _str_prop(title: str, description: str) -> Property:
+    return Property(title=title, json_schema={"title": title, "type": "string", "description": description})
+
+
+recall_memory_tool = ServerTool(
+    name="recall_memory",
+    description="Recall the traveler's durable saved preferences relevant to a query.",
+    inputs=[_str_prop("query", "What to recall, e.g. 'dietary needs' or 'seat preference'.")],
+    outputs=[_str_prop("memories", "Relevant recalled preferences, newline-separated.")],
+)
+
+search_flights_tool = ServerTool(
+    name="search_flights",
+    description="Search available flight options by destination.",
+    inputs=[_str_prop("destination", "Destination city to search for, e.g. 'Amsterdam'.")],
+    outputs=[_str_prop("results", "JSON array of matching flight options.")],
+)
+
+book_flight_tool = ClientTool(
+    name="book_flight",
+    description="Book the chosen flight by its id. The traveler confirms in the UI before it is finalized.",
+    inputs=[_str_prop("flight_id", "The id of the flight to book, e.g. 'AMS-001'.")],
+    outputs=[_str_prop("confirmation", "Human-readable booking confirmation.")],
+)
+
+TOOLS = [recall_memory_tool, search_flights_tool, book_flight_tool]
+# book_flight is client-executed (ClientTool / HITL) — it must NOT appear here.
+TOOL_REGISTRY = {
+    "recall_memory": recall_memory,
+    "search_flights": search_flights,
+}

examples/showcases/oracle-agent-memory/agent/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "concierge-agent"
+version = "0.1.0"
+description = "Oracle Agent Spec × Agent Memory × CopilotKit — travel concierge agent"
+# oracleagentmemory 26.4.0 ships a cp312-only wheel, so pin to 3.12.
+requires-python = ">=3.12,<3.13"
+dependencies = [
+  # Agent Spec → AG-UI adapter (not on PyPI; installed from the ag-ui monorepo).
+  # The [langgraph] extra transitively brings langgraph + langchain + pyagentspec.
+  "ag-ui-agent-spec[langgraph] @ git+https://github.com/ag-ui-protocol/ag-ui.git#subdirectory=integrations/agent-spec/python",
+  # Persistent agent memory on Oracle AI Database, and the DB driver it talks to.
+  "oracleagentmemory==26.4.0",
+  "oracledb>=2.2.0",
+  "langgraph-oracledb>=1.0.1",
+  # HTTP server + env loading.
+  "uvicorn[standard]>=0.30",
+  "python-dotenv>=1.0",
+]
+
+# Runnable app, not a distributable library.
+[tool.uv]
+package = false
+
+[dependency-groups]
+dev = ["pytest>=9.1.1", "pytest-asyncio>=1.4.0"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

examples/showcases/oracle-agent-memory/agent/railway.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://railway.com/railway.schema.json",
+  "build": { "builder": "DOCKERFILE", "dockerfilePath": "Dockerfile" },
+  "deploy": { "healthcheckPath": "/health", "restartPolicyType": "ON_FAILURE" }
+}

examples/showcases/oracle-agent-memory/agent/scripts/reset_memory.py

@@ -0,0 +1,50 @@
+"""Wipe a user's stored memories for a clean demo slate.
+
+Usage (from the agent/ dir):
+    uv run python scripts/reset_memory.py            # resets demo-user
+    uv run python scripts/reset_memory.py some-user
+
+`oracleagentmemory` keys its records by USER_ID, so a scoped DELETE across its
+tables is a clean, deterministic purge (the VECTOR$ index on RECORD_CHUNKS
+self-maintains on DML) — more reliable than deleting search hits one by one, which
+can miss records the ranked search never returns. The agent re-creates preferences
+on the next conversation. Safe to run repeatedly.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+import oracledb
+from dotenv import load_dotenv
+
+load_dotenv()
+
+# Children first; the VECTOR$ index on RECORD_CHUNKS auto-maintains on delete.
+_TABLES = ("RECORD_CHUNKS", "MEMORY", "MESSAGE", "THREAD")
+
+
+def reset(user_id: str) -> dict[str, object]:
+    conn = oracledb.connect(
+        user=os.environ["ORACLE_DB_USER"],
+        password=os.environ["ORACLE_DB_PASSWORD"],
+        dsn=os.environ["ORACLE_DB_DSN"],
+    )
+    cur = conn.cursor()
+    deleted: dict[str, object] = {}
+    for table in _TABLES:
+        try:
+            cur.execute(f'DELETE FROM "{table}" WHERE USER_ID = :1', [user_id])
+            deleted[table] = cur.rowcount
+        except Exception as exc:  # ORA-00942 on a fresh DB (table not created) is fine
+            deleted[table] = f"skip ({type(exc).__name__})"
+    conn.commit()
+    conn.close()
+    return deleted
+
+
+if __name__ == "__main__":
+    target = sys.argv[1] if len(sys.argv) > 1 else "demo-user"
+    result = reset(target)
+    print(f"Reset complete for user {target!r}: {result}")

examples/showcases/oracle-agent-memory/agent/tests/test_oracle_checkpointer.py

@@ -0,0 +1,120 @@
+"""Oracle checkpointer durability round-trip test.
+
+Verifies that LangGraph state written through AsyncOracleSaver actually
+persists in Oracle so that a *fresh* saver (simulating a process restart)
+can read the same thread back from the DB.
+
+Skipped unless ``LANGGRAPH_CHECKPOINTER=oracle`` is set in the environment —
+requires a live Oracle DB with the env vars ``ORACLE_DB_USER``,
+``ORACLE_DB_PASSWORD``, and ``ORACLE_DB_DSN`` present.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+
+import pytest
+from dotenv import load_dotenv
+
+# Module-level skip: entire file is skipped unless Oracle is selected.
+pytestmark = pytest.mark.skipif(
+    os.getenv("LANGGRAPH_CHECKPOINTER", "memory").lower() != "oracle",
+    reason="requires LANGGRAPH_CHECKPOINTER=oracle + a live Oracle DB",
+)
+
+
+async def test_checkpoint_survives_fresh_saver() -> None:
+    """State written through saver1 must be readable through saver2 (same DB).
+
+    This proves durability: the checkpoint lives in Oracle, not in-process RAM.
+    """
+    import oracledb
+    from langchain_core.messages import AIMessage, HumanMessage
+    from langgraph.graph import END, START, MessagesState, StateGraph
+    from langgraph_oracledb.checkpoint.oracle import AsyncOracleSaver
+
+    # Load .env so credentials are available when running from the agent dir.
+    load_dotenv()
+
+    def _require(name: str) -> str:
+        value = os.getenv(name)
+        if not value:
+            raise RuntimeError(
+                f"Missing required environment variable {name!r}. "
+                "Copy agent/.env.example to agent/.env and fill it in."
+            )
+        return value
+
+    user = _require("ORACLE_DB_USER")
+    password = _require("ORACLE_DB_PASSWORD")
+    dsn = _require("ORACLE_DB_DSN")
+
+    # Use a unique thread_id so parallel/repeated test runs don't clash.
+    thread_id = f"verify-{int(time.time())}"
+    config = {"configurable": {"thread_id": thread_id}}
+
+    # ── Trivial graph definition (reused for both compilations) ──────────────
+    def _build_graph(checkpointer):
+        def probe_node(state: MessagesState):
+            return {"messages": [AIMessage(content="durability-probe")]}
+
+        sg = StateGraph(MessagesState)
+        sg.add_node("probe", probe_node)
+        sg.add_edge(START, "probe")
+        sg.add_edge("probe", END)
+        return sg.compile(checkpointer=checkpointer)
+
+    pool1 = None
+    pool2 = None
+    try:
+        # ── Phase 1: write a checkpoint via saver1 ───────────────────────────
+        pool1 = oracledb.create_pool_async(
+            user=user,
+            password=password,
+            dsn=dsn,
+            min=1,
+            max=4,
+            increment=1,
+        )
+        saver1 = AsyncOracleSaver(pool1)
+        await saver1.setup()
+
+        graph1 = _build_graph(saver1)
+        async for _ in graph1.astream(
+            {"messages": [HumanMessage(content="hi")]}, config
+        ):
+            pass
+
+        # ── Phase 2: read it back via saver2 (fresh saver, same DB) ─────────
+        pool2 = oracledb.create_pool_async(
+            user=user,
+            password=password,
+            dsn=dsn,
+            min=1,
+            max=4,
+            increment=1,
+        )
+        saver2 = AsyncOracleSaver(pool2)
+        # No setup() needed to read; tables already exist.
+
+        graph2 = _build_graph(saver2)
+        state = await graph2.aget_state(config)
+
+        # Collect all message contents for assertion.
+        messages = state.values.get("messages", [])
+        contents = [getattr(m, "content", "") for m in messages]
+
+        assert any(
+            "durability-probe" in c for c in contents
+        ), f"Expected 'durability-probe' in messages, got: {contents}"
+
+        assert any(
+            "hi" in c for c in contents
+        ), f"Expected HumanMessage 'hi' in messages, got: {contents}"
+
+    finally:
+        if pool1 is not None:
+            await pool1.close()
+        if pool2 is not None:
+            await pool2.close()