Sessions and memory

Add a tool that creates credit notes

By the end of this lesson, you can continue a conversation and store information for later sessions.

Lesson 6 of 7~15 minScript: 06_memory.sql

1. Lesson 1: Set up the demo and call a model
2. Lesson 2: Create a prompt profile and agent
3. Lesson 3: Add tools that read contract data
4. Lesson 4: Read execution logs and diagnose errors
5. Lesson 5: Add a tool that creates credit notes
6. Lesson 6: Sessions and memory
7. Lesson 7: Review usage and deploy the agent

Sessions and persistent memory

A session retains the messages in one conversation. Memory stores selected information for later conversations:

• A session lets the agent use an earlier invoice reference in a follow-up question.
• Memory lets the agent retrieve a stored customer preference in a new session.

06_memory.sql clears existing memory files for contract 88. Run @06_memory.sql once to enable memory and run both conversation examples. It also demonstrates the error returned when the run context is missing. The following sections explain the script. You do not need to run the excerpts separately.

Continue a conversation with a session ID

Earlier examples used a new session ID for each request. Reuse the ID to continue a conversation. A follow-up sends p_follow_up_message instead of new input parameters:

declare
  l_result  json_object_t;
  l_session varchar2(255 char) := uc_ai_agents_api.generate_session_id;
begin
  l_result := uc_ai_agents_api.execute_agent(
    p_agent_code       => 'SC_DESK'
  , p_input_parameters => json_object_t('{"engineer_name":"Petra","today":"2026-08-24"
      ,"question":"Which invoice on this contract still has an uncredited amount?"}')
  , p_session_id       => l_session
  , p_run_context      => json_object_t('{"contract_id":"88","engineer":"petra.k"}')
  );
  sys.dbms_output.put_line('TURN 1: ' || l_result.get_clob('final_message'));

  -- The follow-up names no invoice. The session carries the first answer.
  l_result := uc_ai_agents_api.execute_agent(
    p_agent_code        => 'SC_DESK'
  , p_follow_up_message => 'And is that one inside the coverage window?'
  , p_session_id        => l_session
  , p_run_context       => json_object_t('{"contract_id":"88","engineer":"petra.k"}')
  );
  sys.dbms_output.put_line('TURN 2: ' || l_result.get_clob('final_message'));
end;
/

After lesson 5, INV-1001 and INV-1003 are fully credited. The first answer can identify INV-1002, which has 350 uncredited but falls outside the coverage window. The follow-up must retain that invoice reference and report that it is outside coverage.

The exact wording varies. Compare the invoice reference across both turns. If the answer is unclear, use the queries from lesson 4 to inspect the messages.

Enable memory for each contract

The script enables memory with the following call:

begin
  uc_ai_memory.enable_for_agent(
    p_agent_code  => 'SC_DESK'
  , p_scope       => uc_ai_memory.c_scope_context
  , p_context_key => 'contract_id'
  );
  commit;
end;
/

Memory is a virtual filesystem in Oracle tables, rooted at /memories. The agent accesses its files through the MEMORY tool. UC AI provides this tool through its tool-calling interface, including for the OpenAI model in this example.

The context scope keys the store on a run-context value, so each contract gets its own memory. Contract 88 and contract 99 cannot read each other’s files. The same contract_id that binds the tools in lesson 3 does a second job here.

enable_for_agent adds the memory tag to the model configuration and keeps the tag lesson 3 put there:

{"g_max_tool_calls":8,"g_tool_tags":["scdesk","memory"],"g_enable_tools":true}

Required run context

Once memory is scoped to contract_id, a run that does not supply it cannot be matched to a store, and UC AI stops the run before it starts:

ORA-20426: The memory of agent "SC_DESK" is scoped to the run-context key
"contract_id", which this run does not supply. Pass it in p_run_context, for
example json_object_t('{"contract_id":"123"}').

The lesson 2 pattern, execute_agent with no p_run_context, stops working here. All later calls must include contract_id in the run context.

Test memory across two sessions

Section 2 of 06_memory.sql runs two requests with different session IDs and the same contract ID. The first supplies a preference absent from the demo customer data:

Conversation 1: Remember for next time: this customer always wants the plant manager Anna Ruiz copied on any credit note, and they prefer email over phone.

Conversation 1gpt-5.6-terra2026-08-24

Noted: copy plant manager Anna Ruiz on any credit note, and use email rather than phone.

The second request starts a new conversation:

Conversation 2: I am about to raise another credit note for this customer. Anything I should know about how they want to be contacted?

Conversation 2gpt-5.6-terra2026-08-24

Use email rather than phone, and copy plant manager Anna Ruiz on every credit note.

Your wording will differ. What must match is the data, and the checks below.

The second request does not name Anna Ruiz. The agent retrieves her name from the memory file created during the first conversation.

Verification

The script lists the memory files and their sizes. You can repeat this query to inspect them:

select store_key
     , path
     , char_count
  from uc_ai_v_memory_files
 where agent_code = 'SC_DESK'
 order by path;

STORE_KEY                        PATH                                             CHAR_COUNT
context:SC_DESK:contract_id:88   /memories/contract_invoice_status.txt                   176
context:SC_DESK:contract_id:88   /memories/customer_communication_preference.txt         152

The store key holds four parts: scope, agent, key, and value. An operator can read or delete the memory of one contract from that string alone.

The view has no content column. To read a file, replace the path in the following block with the path returned by your query, then run the block. Filenames and file sizes can differ from the recorded output:

declare
  l_store_id number;
begin
  l_store_id := uc_ai_memory.resolve_store_id(
    p_scope         => uc_ai_memory.c_scope_context
  , p_agent_code    => 'SC_DESK'
  , p_context_key   => 'contract_id'
  , p_context_value => '88'
  );

  sys.dbms_output.put_line(
    uc_ai_memory.get_file(l_store_id, '/memories/customer_communication_preference.txt'));
end;
/

Current contract customer preference (recorded 2026-08-24): Copy plant manager
Anna Ruiz on every credit note. Customer prefers email rather than phone.

UC AI adds a MEMORY PROTOCOL block to the system prompt. This block instructs the model to maintain memory files. The model chooses their names and contents.

Define what the agent stores

The default protocol applies to every agent. You can add instructions to the profile system prompt to specify what this agent stores. For example:

MEMORY
Record what a conversation told you and no table holds: how this customer wants
to be contacted, who must be copied, what was agreed on the phone.
Do not record anything a tool can read: invoice totals, credited amounts and
coverage dates come from the tools, every time.
Keep one file for each subject, and rewrite a line that stops being true.

This extension is optional. Append the memory instructions to the existing system_prompt_template. Keep the service-desk instructions and placeholders. Use get_prompt_profile and update_prompt_profile, as in lesson 3. Give an Agent a Memory provides the complete procedure and an example of updating an outdated note.

When a memory change takes effect

A memory change reaches the next new session. An open conversation keeps the system prompt it started with, so it also keeps the memory rules it started with.

enable_for_agent writes the memory tag into the profile version the agent resolves to now. uc_ai_prompt_profiles_api.create_new_version copies model_config_json, so a version made that way carries the tag with it. A version you build from scratch carries whatever configuration you pass it.

Memory store before the first run

resolve_store_id reports ORA-20423 for a contract whose agent has never run, because the store does not exist yet. A script that clears the memory before it starts must allow for that:

declare
  e_no_store exception;
  pragma exception_init(e_no_store, -20423);
begin
  -- resolve and clear
exception
  when e_no_store then
    null;  -- no store yet, so it is already empty
end;

Key takeaways

• Reuse a session ID to continue a conversation.
• The context scope gives one memory per business object, keyed on the same run-context value that binds your tools. Read what user scope separates for a comparison with memory keyed on the signed-in user.
• uc_ai_memory.enable_for_agent(p_agent_code => 'SC_DESK', p_scope => 'context', p_context_key => 'contract_id');

Full reference: Agent memory covers every scope, the size caps, and housekeeping.

Next lesson: Review usage and deploy the agentRead session activity and token usage, then deploy the agent configuration to another schema.