Agent memory example v7

Add a help desk conversation to agent memory, check that it was processed, and search the memories that agent memory created from it. This example uses the aidb_memory SQL functions that Managing memories describes.

Run every statement in this example in psql or any SQL client connected to your database. You don't call the Agent Memory Server directly. AIDB sends your conversation turns to it.

Prerequisites

• AIDB is installed in your database. See Installing agent memory.
• The Agent Memory Server is running, your embedding and LLM models are registered, and a namespace is initialized. The examples use a namespace named helpdesk_namespace. See Configuring agent memory.
• Your database role is a member of the aidb_users role. See Granting access to application roles.

Step 1: Adding a conversation

Use aidb_memory.add to submit conversation turns for an actor. The actor is the user or other subject the memory is about. Here the actor is alice.

The turns value is the conversation that you want agent memory to learn from. In your application, it comes from the messages exchanged between the user and your agent. Here it's a sample help desk exchange.

SELECT aidb_memory.add(
  turns           => $$[
    {
      "role": "user",
      "content": "Hi Sam, my annual subscription renewed, but my 20% discount was not applied. I was charged the full $120."
    },
    {
      "role": "assistant",
      "content": "I can help check the renewal and discount history for your account."
    }
  ]$$::jsonb,
  namespace       => 'helpdesk_namespace',
  actor_id        => 'alice',
  agent_id        => 'helpdesk-agent-64849',
  session_id      => 'conv-738949',
  idempotency_key => 'conv-738949-turn-001'
) AS event_id \gset

\echo :event_id

aidb_memory.add returns the ID of the add operation. The \gset command saves it in the event_id psql variable, which the next step uses. If you use another SQL client, copy the ID from the result instead.

The output looks like this. Your ID differs:

                 add
--------------------------------------
 6b387c39-2d4f-40e1-a237-59d5ef134c54
(1 row)

The call accepts the event and returns immediately. The Agent Memory Server then builds memories from the turns in the background, so they aren't searchable straight away.

agent_id, session_id, and idempotency_key are optional. The idempotency key prevents the same event from being stored twice if your application retries the call.

Step 2: Checking processing status

Use aidb_memory.status to check that an event is ready for retrieval. Pass the ID that add returned.

SELECT *
FROM aidb_memory.status(
  id         => :'event_id'::uuid,
  namespace  => 'helpdesk_namespace',
  actor_id   => 'alice',
  agent_id   => 'helpdesk-agent-64849',
  session_id => 'conv-738949'
);

The result shows the state of the event. While agent memory is still working, the state is ACCEPTED or PROCESSING. READY means the memories are ready to retrieve. Run the query again until the state is READY:

                  id                  |     namespace      | status | actor_id |  session_id  |       agent_id       | error_detail
--------------------------------------+--------------------+--------+----------+--------------+----------------------+--------------
 6b387c39-2d4f-40e1-a237-59d5ef134c54 | helpdesk_namespace | READY  | alice    | conv-738949  | helpdesk-agent-64849 |
(1 row)

If the state is FAILED, the error_detail column describes the problem.

Step 3: Searching the memories

Use aidb_memory.search to retrieve the memories that are most relevant to a natural-language query. Use the same actor, agent, and session filters that you used when you added the conversation.

SELECT *
FROM aidb_memory.search(
  query      => 'promo code failed to apply on auto-renewal',
  namespace  => 'helpdesk_namespace',
  actor_id   => 'alice',
  agent_id   => 'helpdesk-agent-64849',
  session_id => 'conv-738949',
  "limit"    => 5
)
ORDER BY score DESC;

The result lists the matching memories with a relevance score:

                  id                  |                                                    content                                                    |   score    | metadata
--------------------------------------+---------------------------------------------------------------------------------------------------------------+------------+----------
 3e39ed49-e377-48a6-b5a4-7545a34a7a30 | User's annual subscription renewed, but the 20% discount was not applied, resulting in a charge of $120.      | 0.54703873 | {}
(1 row)

The memory text and scores depend on your models, so your results can differ. The query doesn't need to use the same words as the original conversation, because search matches on meaning, not on exact wording.

What you built

You stored a conversation for one user, waited for agent memory to turn it into memories, and retrieved the ones relevant to a new question. An agent can run the search step before it responds, so that it remembers what the user told it earlier.

Next steps

• Managing memories: list and delete memories.
• Using session memory: read the current conversation back in order.