Sessions and memory

A session stores the messages of a conversation so an agent remembers earlier turns.

Pick the kind of memory you need:

Memory	Keeps	Lasts
Session	The turns of one conversation with one agent	Until you delete the session
Shared memory	Facts an agent saves and recalls, optionally per end user	Across sessions, runs and agents

Sessions live on the server, bound to one agent. Any client that has the session ID can resume the conversation. Session data is stored, not used for training.

Try it

Create a session with aix.Session, then pass it to every run in the conversation.

from aixplain import Aixplain

aix = Aixplain(api_key="YOUR_API_KEY")

agent = aix.Agent(
    name="Support agent",
    description="Answers customer questions and remembers the conversation.",
    instructions="You are a helpful assistant. Use the conversation so far to answer.",
).save()

session = aix.Session(agent=agent, name="Support chat").save()

agent.run("My name is Adam and my favorite color is orange. Remember that.", session=session)
result = agent.run("What is my name, and what is my favorite color?", session=session)
print(result.data.output)

Show output

session takes a Session object or a session ID string.

Resume a session

The transcript lives on the server, so a fresh client resumes the conversation from the session ID.

same_agent = aix.Agent.get(agent.id)

result = same_agent.run("Remind me, what color did I say was my favorite?", session=session.id)
print(result.data.output)

Show output

Inject history

To give one run some prior turns without a session, pass history. Nothing is stored on the server, and history cannot be combined with session.

history = [
    {"role": "user", "content": "What is the capital of France?"},
    {"role": "assistant", "content": "The capital of France is Paris."},
]

result = agent.run("Tell me one fun fact about it. One sentence.", history=history)
print(result.data.output)

Show output

Read messages

Each run adds a user message and the agent's assistant reply to the session. Read the transcript with messages().

for message in session.messages():
    print(message.sequence, message.role, message.content[:60])

Show output

You can also add, fetch and delete messages directly. Attach media to a message with attachments, as a URL or a local path.

message = session.add_message(
    role="user",
    content="Please review this image.",
    attachments=["https://upload.wikimedia.org/wikipedia/commons/3/3a/Cat03.jpg"],
)
print(len(message.attachments))

fetched = session.get_message(message.id)
print(fetched.content)

session.delete_message(message.id)

Show output

Find sessions

aix.Session.search() returns a page of sessions. Filter by agent, status, creation date, or whether memory is on.

page = aix.Session.search(agent=agent, created_after="2026-01-01T00:00:00Z")
print(page.total)
for item in page.results:
    print(item.name, item.status, item.message_count)

Show output

memory_enabled=True returns sessions, and memory_enabled=False returns one-off runs.

Rename, copy and delete

Sessions are not deleted automatically. Delete them when you are done.

session = aix.Session.get(session.id)
session.name = "Support chat (resolved)"
session.save()

copy = session.clone().save()
print(session.name, "|", copy.name)

copy.delete()
session.delete()

Show output

Share memory across sessions

Shared memory is a tool that keeps a text buffer of facts. The agent writes to it when the user shares something durable and reads it at the start of each run, so facts survive across sessions and runs.

Asset path: aixplain/shared-memory/aixplain · Marketplace card

memory = aix.Tool(
    integration="aixplain/shared-memory/aixplain",
    name="Account memory",
    description="Durable notes about customer accounts.",
).save()

account_agent = aix.Agent(
    name="Account assistant",
    description="Remembers account facts and answers from them.",
    instructions="Save durable facts the user shares to memory. Answer account questions from memory.",
    tools=[memory],
).save()

account_agent.run("Remember: ACME Corp uses Jira Cloud and wants status updates every Monday.")
result = account_agent.run("Which tracker does ACME Corp use, and when do they want updates?")
print(result.data.output)

Show output

The second run has no session and no history. The answer comes from the memory buffer. Connecting the tool needs no third-party credentials and creates a private tool in your workspace.

Read and write memory directly

Call the tool yourself to seed or inspect the buffer.

memory.run(action="insert", data={"content": "Globex prefers email over calls."})

result = memory.run(action="get", data={})
print(result.data)

Show output

Action	What it does
insert	Appends content to the buffer.
get	Returns the whole buffer as text.
update	Replaces the whole buffer with content.
optimize	Compresses and cleans up the buffer with the memory manager model.

Keep memory per user

Pass an identifier to read and write a separate buffer for each end user. A buffer is empty until something is written under its identifier.

memory.run(action="insert", data={"identifier": "customer-123", "content": "Prefers concise answers and CSV exports."})

for user in ["customer-123", "customer-456"]:
    result = memory.run(action="get", data={"identifier": user})
    print(user, "->", repr(result.data))

Show output

Configure the buffer

Pass these fields in config when you create the tool, for example config={"max_memory_size": 256, "size_management_policy": "summarize"}. All are optional.

Field	Default	Description
max_memory_size	1028	Maximum buffer size, in words.
size_management_policy	"forget"	Past the limit, "forget" drops the oldest lines and "summarize" compresses older content with an LLM.
memory_manager_model	platform default	Asset ID or name of the LLM used by "summarize" and optimize.

Delete the agent and the tool when you no longer need them.

account_agent.delete()
memory.delete()
agent.delete()

Reference

Parameter	Type	Default	Description
agent	Agent or str	required	The agent the session is bound to, as an object or an ID.
name	str	None	Display name for the session.

Method	What it does
aix.Session(agent=..., name=...).save()	Create a session.
aix.Session.get(session_id)	Retrieve a session.
aix.Session.search(agent=..., ...)	List sessions as a page.
session.messages()	Read the transcript.
session.add_message(), get_message(), delete_message()	Manage single messages.
session.clone(), session.delete()	Copy or remove a session.

Troubleshooting

Symptom	Cause	Fix
The agent forgets earlier turns	The run did not receive the session	Pass session=session (or the session ID) on every run in the conversation.
UserWarning: Per-run execution overrides (budget ...) were passed alongside session	The agent has a budget, which is copied into the session's stored settings	Expected. No action needed.
ValueError: session=… runs do not support legacy run kwargs: ['history']	history and session were passed together	Use one or the other. A session already holds the history.

Next steps

• Budgets: cap the cost and length of every run.
• Tracing and monitoring: see each step, tool call and credit.
• REST API: run multi-turn conversations from any language.
• API reference: session: every parameter and method.