---
title: "Overview"
description: "Persistent user memory on a knowledge graph — usable with the AI Gateway or standalone."
---

> Documentation Index
> Fetch the complete documentation index at: https://truememory-docs.mvstg.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

Truememory stores user memories in a knowledge graph (powered by [Graphiti](https://github.com/getzep/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](/ai-gateway/chat-completions/) request automatically. Nothing to integrate.
- **Standalone** — you run your own LLM and call the memory endpoints directly: [add data](/memory/add-data/), [retrieve context](/memory/retrieval/), and manage what's stored.

All memory endpoints require a Bearer token from [Truememory Auth](/authentication/overview/). Backend services can instead use [service auth](/authentication/service-accounts/) 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:

- **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](/memory/retrieval/#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](/ai-gateway/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](/memory/graph-namespacing/): 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](/ai-gateway/chat-completions/) |
| Make a session's first request fast | warm the user cache on login/app-open | [Search & retrieval](/memory/retrieval/#warming-the-user-cache) |
| Feed in outside data (CRM, onboarding, notes) | add data to the graph | [Adding data](/memory/add-data/) |
| Get chat-identical context for your own LLM | retrieve memory context | [Search & retrieval](/memory/retrieval/#retrieve-memory-context) |
| Get raw ranked facts for a query | search memory | [Search & retrieval](/memory/retrieval/#search-memory) |
| Render an interactive graph view | memory graph | [Building memory UIs](/memory/building-uis/#memory-graph-visualization) |
| Build a "Memories" tab or feed | memory timeline | [Building memory UIs](/memory/building-uis/#memory-timeline) |
| Collapse duplicate entities | merge | [Building memory UIs](/memory/building-uis/#merge-two-memories) |
| Let a user delete a memory | delete | [Building memory UIs](/memory/building-uis/#delete-a-memory) |
| Back up, migrate, or hand over a user's memory | export & import | [Export & import](/memory/export-import/) |
| Share knowledge across users | graph namespaces | [Graph namespacing](/memory/graph-namespacing/) |

Source: https://truememory-docs.mvstg.com/memory/overview/index.mdx