Long-Term Memory: Persistent User Facts

Store semantic facts about users in vector storage so agents recall preferences and context across every conversation, not just the current one.

Long-term memory lets Agent Manager store semantic facts about a user—preferences, decisions, background context—in a pgvector table that persists across all sessions. Unlike session history, which is scoped to a single conversation, memory is permanent until you explicitly delete it. When an agent starts a new conversation, it searches memory for relevant facts and uses them to personalize its response without you having to repeat yourself.

How agents use memory

During a conversation, agents can call two built-in tools automatically:

• save_memory(content) — stores a new fact extracted from the conversation.
• search_memory(query) — performs a semantic vector search over stored facts to retrieve relevant context.

You do not configure these tools manually. When an agent detects information worth remembering (a user preference, a decision, a correction), it calls save_memory. When it needs context from past interactions, it calls search_memory. Both happen transparently as part of the agent’s reasoning loop.

Long-term memory is distinct from session history. Session history records the raw message transcript for a single conversation. Memory stores distilled facts that travel with the user indefinitely.

Adding a memory

You can add facts programmatically using POST /api/memories. This is useful for seeding initial context—for example, onboarding information from your CRM—before a user’s first conversation.

curl -X POST http://localhost:8080/api/memories \
  -H "Content-Type: application/json" \
  -d '{"content": "The user prefers responses in Spanish and works in the healthcare industry."}'

Response

{
  "status": "saved"
}

content · string · required

The fact to store. Write facts as plain prose sentences. The content is embedded as a vector, so descriptive natural-language phrasing improves retrieval accuracy.

Searching memories

GET /api/memories performs a semantic vector search and returns the facts most relevant to your query. This is the same mechanism agents use internally when calling search_memory.

curl "http://localhost:8080/api/memories?query=communication+preferences"

Response

[
  "The user prefers responses in Spanish and works in the healthcare industry.",
  "The user previously requested that summaries be limited to three bullet points."
]

Results are ranked by semantic similarity to the query string.

Deleting memories

To remove specific memories, send a DELETE /api/memories request with a JSON array of memory IDs in the body.

curl -X DELETE http://localhost:8080/api/memories \
  -H "Content-Type: application/json" \
  -d '["mem-uuid-1", "mem-uuid-2"]'

Returns 204 No Content on success.

Deleted memories cannot be recovered. If an agent saved a memory automatically during a conversation, deleting it here removes it permanently.

Optimizing memory

Over time, a user’s memory store can accumulate redundant or outdated facts. POST /api/memories/optimize triggers an LLM-based consolidation pass that deduplicates overlapping facts, resolves contradictions, and improves overall memory quality.

curl -X POST "http://localhost:8080/api/memories/optimize?userId=user-123"

Response

{
  "status": "optimization_started"
}

Optimization runs asynchronously. Run it periodically—for example, after a user completes a long onboarding flow—or on a scheduled basis for active users.

Memory optimization is especially effective after a user has had several conversations. Early optimization on sparse memory stores has minimal benefit.

Memory statistics

GET /api/memories/stats returns usage statistics for a given user’s memory store. Use this to monitor memory growth and decide when to run optimization.

curl "http://localhost:8080/api/memories/stats?userId=user-123"

Response

{
  "totalMemories": 47,
  "oldestMemoryDate": "2026-01-15T08:30:00Z",
  "lastUpdated": "2026-05-06T09:00:00Z"
}

Memory topics

GET /api/memories/topics returns high-level topic clusters derived from a user’s stored facts. Use this to build summary views in your UI or to understand what the agent knows about a user at a glance.

curl "http://localhost:8080/api/memories/topics?userId=user-123"

Response

[
  "Communication preferences",
  "Industry and role",
  "Product usage patterns",
  "Past support interactions"
]

Memory vs. session history

	Long-term memory	Session history
Scope	All sessions, all time	A single conversation
Storage	Vector database	Relational database
Retrieval	Semantic similarity search	Chronological message replay
Managed by	save_memory / search_memory tools	Automatic per-session context
Deleted with	DELETE /api/memories	DELETE /api/sessions/{sessionId}

For more on session history, see Sessions: Conversation History and Context.