> ## 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
> Organization-wide knowledge the agent always carries
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.
```mermaid theme={"dark"}
graph LR
Alice --- S1["Session 1"]
Alice --- S2["Session 2"]
Bob --- S3["Session 3"]
S1 --- Agent["Support Bot"]
S2 --- Agent
S3 --- Agent
Agent --- GM[("Agent Memory")]
```
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](/developers/frameworks/agno) for the manual integration story.
## When to use agent memories
Pick the right layer for the fact:
| The fact applies to... | Use |
| --------------------------------- | ------------------------------------------------------- |
| One specific user | [User memory](/developers/memory/user-memories) |
| A single conversation | [Session storage](/developers/memory/session-storage) |
| Every conversation this agent has | **Agent memory** |
| A queryable document corpus | [Knowledge base](/developers/knowledge/semantic-search) |
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](https://app.xpander.ai). Agent memories are single-agent only; the wiring is skipped on Teams.
UI walkthrough for toggling agent memory and switching between agentic and manual modes.
| Setting | What it controls | Default |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------- | ------- |
| `agent_memories` | Turn cultural-knowledge storage on. The agent reads entries into the system prompt every turn. | `False` |
| `agentic_culture` | When 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:
```python theme={"dark"}
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
```python highlight={5,7-12} theme={"dark"}
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:
| Field | Type | What it's for |
| ------------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `summary` | `str` | A condensed version of `content`. Shown in previews; useful for long entries where you want a shorter form in logs or admin UIs. |
| `categories` | `list[str]` | Tags for grouping or filtering entries (`["policy"]`, `["engineering", "ops"]`). |
| `notes` | `list[str]` | Free-form annotations (caveats, sources, change history). Not injected into the agent's context directly. |
| `input` | `str` | The 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. |
| `metadata` | `dict` | Arbitrary 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
```python highlight={1} theme={"dark"}
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`:
```python highlight={3,5} theme={"dark"}
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:
```python theme={"dark"}
await db.delete_cultural_knowledge(id="cul_existing_id")
```
To wipe every entry on the agent (destructive, no confirmation):
```python theme={"dark"}
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](/developers/knowledge/semantic-search) 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](/developers/knowledge/semantic-search) 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
Per-user facts, the layer below.
Single-conversation memory.
For larger bodies of knowledge the agent retrieves on demand.
The full args-dict reference, including `add_culture_to_context` and the agentic-culture wiring.