← Back to Agent
Agent Memory
Manage the agent's persistent knowledge store — create, search, browse, prune, and decay memories across sessions.
Overview
For Everyone
Agent Memory is the agent's long-term brain. Without memory, an agent forgets everything between sessions. With memory, it can recall facts about your organization, remember past interactions, learn from mistakes, and build up expertise over time. You can manually add knowledge, search what the agent knows, and clean up outdated information.
For Developers
The Memory section interfaces with these endpoints:
GET /memory/agent/:agentId?limit=200&search=…&category=…&importance=… — Query memories with server-side filtering.GET /memory/agent/:agentId/stats — Aggregate statistics (total entries, by category, by source, avg confidence).POST /memory — Create a new memory entry with title, content, category, importance, and tags.DELETE /memory/:id — Delete a specific memory (with confirmation dialog).POST /memory/agent/:agentId/prune — Remove expired/stale entries.POST /memory/agent/:agentId/decay — Apply confidence decay (default rate: 10%).
Client-side date filtering and pagination (10 items/page) are applied on top of server-side results.
How It Works
- Load — Memories and stats are fetched in parallel. Stats show totals; memories show individual entries.
- Browse — Memories appear in a compact grid layout with title preview, category badge, importance level, confidence bar, and date.
- Expand — Click any row to expand it and see the full content, source, creation date, last accessed date, tags, and a delete button.
- Filter — Use the search box (triggers on Enter), category dropdown, importance dropdown, and date range to narrow results. Category and importance filters trigger server-side re-fetch.
- Create — Click "Add" to open a modal where you enter a title, content, category, importance, and tags.
- Maintain — Use the prune (trash icon) and decay (clock icon) buttons for automated memory management.
Key Concepts
Memory Categories
Each memory is classified into one of 11 categories, each with a distinct color:
| Category | Description |
|---|
| Org Knowledge | Facts about your organization — structure, policies, processes. |
| Preference | User or organizational preferences the agent should respect. |
| Interaction Pattern | Learned communication styles and behavioral patterns. |
| Context | Situational context from previous interactions. |
| Skill | Capabilities or techniques the agent has learned. |
| Processed Email | Summaries of emails the agent has processed. |
| Procedure | Step-by-step processes the agent should follow. |
| Relationship | Information about people and relationships. |
| Reflection | Agent self-assessment and lessons learned. |
| Domain Expertise | Specialized knowledge in a specific domain. |
| Error Pattern | Known error scenarios and their resolutions. |
Confidence & Decay
Every memory has a confidence score (0-100%) shown as a color-coded progress bar:
- Green (≥80%) — High confidence. The agent trusts this information.
- Yellow (50-79%) — Moderate confidence. May need verification.
- Red (<50%) — Low confidence. The information may be outdated or unreliable.
Decay simulates forgetting. Running decay reduces confidence of memories that haven't been accessed recently by a configurable rate (default 10%). This ensures frequently-used knowledge stays strong while rarely-accessed information gradually fades.
Importance Levels
- Critical — Must never be forgotten. Core organizational facts.
- High — Important for daily operations.
- Normal — Standard knowledge.
- Low — Nice-to-have context that can be pruned if needed.
Stats Bar
The compact stats bar shows four metrics at a glance:
- Total — Total memory entries stored.
- Categories — Number of distinct categories in use.
- Avg Confidence — Average confidence across all memories.
- Sources — Number of distinct sources that contributed memories.
Filtering & Search
- Search — Text search (press Enter to execute). Sent to the server as a query parameter.
- Category — Dropdown filter. Triggers a server-side re-fetch.
- Importance — Dropdown filter. Triggers a server-side re-fetch.
- Date Range — Client-side date filtering on
createdAt.
Creating Memories
The "Add" button opens a creation modal with:
- Title — Required. A concise summary of the knowledge.
- Content — Required. The detailed information.
- Category — Select from the 11 available categories.
- Importance — Critical, High, Normal, or Low.
- Tags — Comma-separated tags for additional organization.
Memory Maintenance
Warning: Both prune and decay are irreversible operations. Prune permanently deletes entries; decay permanently reduces confidence scores.
- Prune (🗑) — Removes expired and stale entries with low confidence. Shows a confirmation dialog and reports how many entries were deleted.
- Decay (🕐) — Reduces confidence by 10% for memories not recently accessed. Shows a confirmation dialog and reports how many entries were affected.
Best Practices
- Seed important knowledge manually — Don't wait for the agent to learn everything on its own. Add critical org knowledge, procedures, and preferences directly.
- Use appropriate categories — Proper categorization helps the agent retrieve relevant information faster during operation.
- Run prune periodically — Stale memories can confuse the agent. Prune monthly to keep the knowledge base clean.
- Run decay sparingly — Decay is useful for identifying unused knowledge, but running it too often can erode valid memories. Monthly or quarterly is sufficient.
- Set critical importance for must-know facts — Critical memories resist pruning and decay. Use this for non-negotiable organizational rules.
- Use tags for cross-cutting concerns — Tags let you find related memories across categories (e.g., tag "onboarding" across procedures, preferences, and org knowledge).
- Monitor average confidence — A dropping average may mean the agent's knowledge is going stale. Add fresh memories or reinforce existing ones.
Troubleshooting
Search returns no results
Search is server-side and may not support fuzzy matching. Try shorter or more specific search terms. Also check that category and importance filters aren't excluding results.
Memory deleted accidentally
Memory deletion is permanent — there is no undo. The confirmation dialog exists to prevent accidental deletions. If critical knowledge was lost, you'll need to recreate it manually.
Confidence dropping unexpectedly
Someone may have run the decay operation. Check the activity log for decay actions. To prevent this, set important memories to "Critical" importance.
Too many memories slowing down the agent
Large memory stores can slow retrieval. Prune low-confidence and low-importance entries. Consider consolidating multiple related memories into fewer, more comprehensive ones.
Organization Context
When an agent belongs to a client organization, memory is scoped for data isolation:
- Data Isolation — Memory entries are scoped to the organization. An info banner confirms this with "Memory entries are scoped to [Org Name] for data isolation."
- Org-Labeled Entries — Memories created within an organization context are tagged with the org identifier, ensuring they don't leak across organizational boundaries.
- Search & Filtering — Memory queries automatically respect org boundaries. Only memories belonging to the agent's organization are returned.
Can an agent access memories from another organization?
No. When an agent belongs to a client organization, its memory queries are automatically scoped to that organization. This ensures complete data isolation between client organizations.