Agent Memory

By default, each call to your agent is stateless: the agent only sees the message you just sent. That's fine for one-shot tasks (classification, extraction, single answers) but breaks down for anything conversational.

HeroMate includes built-in memory so the agent can remember what was said earlier — either within a single conversation or across every conversation a user has ever had.

Memory modes

Pick the mode in the agent node's Memory field.

How session memory works

When memory_mode = session:

1. Your frontend generates (or stores) a session_id for each conversation.
2. Every time the user sends a message, you pass the same session_id.
3. The agent loads the previous messages for that session, adds the new user message, calls the model, and persists the new assistant reply.

A new session_id = a fresh conversation, no memory carried over. The SDK's useChat() hook handles this automatically.

How user memory works

When memory_mode = user:

• No session_id is needed. The agent uses the authenticated user's ID from the JWT.
• Every message from that user anywhere in your app is merged into one rolling history.
• Good for "personal assistant" experiences where you want continuity across days and devices.

The memory window

Loading all messages forever would blow up the model's context window and your token bill. HeroMate controls this with two knobs:

The two limits are applied together — whichever triggers first wins. The agent always sees the most recent messages.

Where memory is stored

Memory lives in your own project database, in two system tables:

• system.ai_chats — one row per chat session, with id, user_id, endpoint_id, and metadata
• system.ai_messages — one row per message, with chat_id, role, and parts (the full Vercel AI SDK message format)

These tables are created automatically the first time an agent with memory runs. You can query them with execute_sql like any other table — useful for building chat history UIs or moderation dashboards.

Listing past conversations

The SDK gives you a hook to list a user's past sessions. useChatList takes an options object (not a positional string):

import { useChatList } from '@dypai-ai/client-sdk/react'

function ConversationsSidebar() {
  const { chats, isLoading, error, deleteChat, renameChat, refetch } =
    useChatList({ endpointId: '<endpoint_id>', limit: 50 })

  return (
    <ul>
      {chats.map(c => (
        <li key={c.id}>
          <a href={`/chat/${c.id}`}>{c.title ?? 'Untitled'}</a>
        </li>
      ))}
    </ul>
  )
}

useChatList({ endpointId, limit, enabled }) returns:

• chats — the list of conversations
• isLoading / error — load state
• deleteChat(chatId) — delete a conversation
• renameChat(chatId, title) — rename a conversation
• refetch() — reload the list

Combined with useChat('endpoint', { id }), this gives you the classic ChatGPT-style "sidebar with all my past conversations" for free. (The resume option is id, not sessionId.)

Clearing memory

Users occasionally want a fresh start. Your options, easiest first:

1. Delete a conversation (recommended): call deleteChat(chatId) from useChatList. It removes the chat and its messages — no backend code needed. Wire it to a "Delete this conversation" button.
2. New conversation: start a fresh chat with useChat('endpoint', { id: newId }) (or no id). The old conversation stays stored but isn't loaded.
3. Advanced (optional): delete the row directly from system.ai_chats with SQL (cascades to messages) — useful for bulk cleanup or admin tooling.

Memory and tool calls

Tool calls are stored as part of the conversation. When memory is loaded, the model sees:

• User messages
• Assistant replies
• Tool calls the assistant made
• Tool results returned

This means the agent remembers what data it fetched earlier and doesn't have to call the same tool twice. If the user asks "what were my orders again?", the agent can answer from memory without re-querying your database.

Privacy notes

• Memory is scoped per project — agents in one project can't see conversations in another.
• User memory is scoped per user — users can't see each other's history.
• Memory data is stored in your project database alongside your regular tables. Your existing backups, access controls, and data deletion flows apply.
• For GDPR-style deletion, simply delete rows from system.ai_chats for the relevant user.

Next steps