Truememory stores user memories in a knowledge graph (powered by Graphiti and Neo4j). It automatically extracts entities, relationships, and facts from conversations and uses them to give the LLM context about the user in future requests.
Memory works two ways:
- With the AI Gateway — memory is injected into every chat completions request automatically. Nothing to integrate.
- Standalone — you run your own LLM and call the memory endpoints directly: add data, retrieve context, and manage what’s stored.
All memory endpoints require a Bearer token from Truememory Auth. Backend services can instead use service auth with X-On-Behalf-Of (Truememory user UUID) or X-External-User-Id (your own user IDs).
How memory works
Every chat turn runs two memory fetches concurrently, and both land in the LLM’s context:
context
retrieval
- Session context — the “Known Entities / Known Facts” block. Cached 5 minutes per user; falls back to a fast database query when cold.
- Per-message retrieval — a hybrid graph search (BM25 + cosine similarity + graph traversal + reranking) against this specific message. Skipped for low-information messages (“hi”, “ok”).
On top of the automatic injection, the LLM can call three server-side memory tools mid-conversation — invisible to the client: memory_search, memory_write, and memory_get.
After each turn, Truememory records the exchange and extracts new entities and facts from it in the background. No extra API calls are needed — injection, tools, and recording are all automatic on the gateway path. If you run your own LLM, Retrieve Memory Context returns exactly what this pipeline would inject, as ready-made prompt blocks.
The graph model
Three kinds of records make up a user’s memory:
| Record | What it is | Example |
|---|---|---|
| Entity (node) | A person, place, project, or concept, with a prose summary | Mindvalley — “You were promoted to Staff Engineer at Mindvalley.” |
| Fact (edge) | A natural-language statement connecting two entities | Fauzaan —works_at→ Mindvalley |
| Episode | The raw conversation chunk or ingested data a fact was extracted from | a recorded chat exchange |
Facts carry two timestamps: created_at (when recorded) and valid_at (when it became true in the real world). Entity summaries come in two renditions — summary (humanized, addresses the user as “you”) and summary_raw (Graphiti’s third-person dossier style).
Memory scoping
Each agent is configured with a memory scope that controls how memories are shared:
| Scope | Behavior | Example |
|---|---|---|
shared |
Memories are accessible across all agents using the shared pool | chatbot, research-assistant |
agent |
Memories are isolated to that specific agent | rag-assistant |
Memory scope is set per agent — clients cannot override it. See Agents for per-agent scope details.
User memory vs. graph namespaces
Everything above describes user memory — one graph per user. For knowledge that should be shared across users (a product catalog, a coach’s methodology, tenant-wide facts), Truememory has graph namespaces: standalone graphs written by your backend and blended into any user’s retrieval via graph_ids.
Choosing an endpoint
| You want to… | Use | Where |
|---|---|---|
| Chat with memory, zero integration | POST /v1/chat/completions — injection is automatic |
Unified API |
| Make a session’s first request fast | warm the user cache on login/app-open | Search & retrieval |
| Feed in outside data (CRM, onboarding, notes) | add data to the graph | Adding data |
| Get chat-identical context for your own LLM | retrieve memory context | Search & retrieval |
| Get raw ranked facts for a query | search memory | Search & retrieval |
| Render an interactive graph view | memory graph | Building memory UIs |
| Build a “Memories” tab or feed | memory timeline | Building memory UIs |
| Collapse duplicate entities | merge | Building memory UIs |
| Let a user delete a memory | delete | Building memory UIs |
| Back up, migrate, or hand over a user’s memory | export & import | Export & import |
| Share knowledge across users | graph namespaces | Graph namespacing |