Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.xpander.ai/llms.txt

Use this file to discover all available pages before exploring further.

Agent memories are facts the agent should know in every conversation, regardless of who is talking to it. Use them for things that should be true everywhere your agent runs: “Our refund policy is 30 days.” “We use JIRA for bug tracking, Linear for product.” “All deploys ship on Tuesdays and Thursdays.” Unlike user memories, agent memories are scoped only to agent_id. Any memory created here becomes part of every conversation for every user.
Agent memories are wired in automatically only for Agno. The DB connection and helpers on this page raise NotImplementedError on LangChain, OpenAI Agents SDK, and AWS Strands. See the framework pages for the manual integration story.

​
When to use agent memories

Pick the right layer for the fact:
The fact applies to…Use
One specific userUser memory
A single conversationSession storage
Every conversation this agent hasAgent memory
A queryable document corpusKnowledge base
A useful test: if the fact is short (one or two sentences) and would matter on every turn, it’s an agent memory. If it’s a multi-page document the agent might need sometimes, it belongs in a knowledge base. Agent memories vs. system prompt instructions: instructions are part of the agent’s identity and require an Agent Studio change to update. Agent memories are mutable from code, so an automation can update them when the underlying fact changes. “Refund window is 14 days” is policy that might shift quarterly; encoding it as a memory means a single SDK call keeps the agent current, no UI round-trip needed. In agentic mode the agent can also extract and add memories itself, which instructions can’t do.

​
Configuration

Settings live on agent.agno_settings and are toggled in the agent’s Memory tab in Agent Studio. Agent memories are single-agent only; the wiring is skipped on Teams.

Configure memory in Agent Studio

UI walkthrough for toggling agent memory and switching between agentic and manual modes.
SettingWhat it controlsDefault
agent_memoriesTurn cultural-knowledge storage on. The agent reads entries into the system prompt every turn.False
agentic_cultureWhen on, the agent identifies and stores org-level facts as it learns them. When off, your code writes through the SDK.False
Read which mode is active off the loaded agent: 
xpander_agent = await Agents().aget(agent_id="agt_01H...")
print(xpander_agent.agno_settings.agent_memories)
print(xpander_agent.agno_settings.agentic_culture)
Manual vs agentic mode, pick one:
  • Manual mode (agent_memories = True): you write the memories. The agent reads them during reasoning. Good for facts you want strict control over: compliance text, policy wording.
  • Agentic mode (agentic_culture = True): the agent identifies and stores org-level facts as it learns them through conversations. Good when you want the agent to build up its own picture of how your org operates.
Both inject memories into the agent’s system prompt at the start of every turn with no retrieval step needed. The two modes are mutually exclusive.

​
Add a memory

To add an Agent Memory, you need:
  • a name identifying the memory
  • content that carries the main body text
from agno.db.schemas.culture import CulturalKnowledge
from xpander_sdk import Agents

agent = await Agents().aget(agent_id="agt_01H...")
db = await agent.aget_db(async_db=True)

await db.upsert_cultural_knowledge(
    CulturalKnowledge(
        name="refund-policy",
        content="Refund policy: full refund within 30 days, partial after.",
    )
)
You can also specify some optional parameters:
FieldTypeWhat it’s for
summarystrA condensed version of content. Shown in previews; useful for long entries where you want a shorter form in logs or admin UIs.
categorieslist[str]Tags for grouping or filtering entries (["policy"], ["engineering", "ops"]).
noteslist[str]Free-form annotations (caveats, sources, change history). Not injected into the agent’s context directly.
inputstrThe original text or conversation turn that produced this memory, when set by agentic mode. Useful for auditing what prompted the agent to store a fact.
metadatadictArbitrary key-value pairs for your own tooling (timestamps, author, source system, etc.). Not read by the agent.
agent_id and team_id are set automatically by the SDK from the loaded agent. Don’t set them manually.

​
Inspect memories

memories = await db.get_all_cultural_knowledge()
for m in memories:
    print(m.id, m.name, m.content)
Use this to audit what agentic mode has accumulated, build an admin view, or verify that a seed run actually wrote. Filter by name or limit if the store has grown large.

​
Edit or delete

To edit, upsert with an existing id: 
await db.upsert_cultural_knowledge(
    CulturalKnowledge(
        id="cul_existing_id",
        name="refund-policy",
        content="Refund policy: full refund within 14 days, partial after.",
    )
)
To remove one record: 
await db.delete_cultural_knowledge(id="cul_existing_id")
To wipe every entry on the agent (destructive, no confirmation): 
await db.clear_cultural_knowledge()

​
Token cost

Agent memories live in the system prompt, which means they are injected in the prompt sent to the LLMs in every turn. This increases cost and latency. Keep entries short and high-signal. Prune periodically. If the store has grown past the point where every entry is genuinely useful on every turn, move the excess to a knowledge base where it’s retrieved on demand rather than always injected.

​
Troubleshooting

Confirm agent_memories=True (or agentic_culture=True) is set via xpander_agent.agno_settings, then reload the agent so the next task picks up the new memory. Cached Agent instances from before the insert won’t reflect it until Agents().aget(...) runs again.
List with db.get_all_cultural_knowledge(), find the row, and call db.delete_cultural_knowledge(id=...). Since agent memories are global, a single bad row affects every user; fix it quickly. For ongoing protection, switch from agentic_culture to agent_memories (manual mode) so the agent can no longer write on its own.
In agentic_culture mode the agent will rewrite memories it considers important. If a deleted memory keeps reappearing, switch to manual mode (agent_memories=True) so the agent stops writing entirely, or rephrase the underlying fact so the agent doesn’t infer the same thing again.
Too many agent memories. Prune aggressively or move long-form content to a knowledge base where it’s retrieved on demand. A useful rule: anything you wouldn’t want to read on every turn shouldn’t live in agent memories.
Agent memories are single-agent only; the cultural-knowledge wiring is skipped on Teams by design. If you have a multi-agent setup and need shared organizational facts, attach them to each member agent individually, or move the content into a knowledge base the team shares.

​
Next steps

User memories

Per-user facts, the layer below.

Session storage

Single-conversation memory.

Knowledge bases

For larger bodies of knowledge the agent retrieves on demand.

Agno framework

The full args-dict reference, including add_culture_to_context and the agentic-culture wiring.