Core Concepts
Memgraph organizes AI agent memory into a multi-layer pipeline. Each layer serves a specific purpose in transforming raw interactions into usable knowledge.
Events
Events are the raw interactions your application streams into Memgraph. Every user message, tool call, agent response, or system log is an event.
event_typeType of event: user_message, agent_response, tool_call, system_log
contentJSON payload with the event data (e.g., {text: '...'})
thread_idGroups events into conversations. Events in the same thread form a sequence.
user_idThe end-user this event belongs to. Used for per-user memory scoping.
agent_idThe AI agent that produced or received this event.
tenant_idYour tenant (workspace). All queries are scoped by this.
Events are append-only. Once ingested, they cannot be modified. They are the source of truth for everything downstream.
Episodes
Episodes are temporal clusters of events. Memgraph automatically segments a continuous stream of events into discrete episodes — typically one per conversation session or task.
summaryLLM-generated summary of what happened in this episode.
tagsAuto-extracted topic tags (e.g., ['deployment', 'kubernetes']).
outcomeHow the episode ended: completed, abandoned, escalated.
consolidation_statuspending → processing → consolidated. Tracks dreaming progress.
Episodes are the bridge between raw events and extracted knowledge. During Cognitive Dreaming, pending episodes are processed to extract beliefs.
Beliefs
Beliefs are the long-term memory layer — semantic facts extracted from episodes or stored directly. They represent what Memgraph "knows" about a user, with confidence scores and versioning.
keyWhat the belief is about (e.g., 'preferred_language').
valueThe actual knowledge (e.g., 'Python 3.12').
confidence0.0 to 1.0. How certain this belief is. Decays or strengthens over time.
belief_typefact (verified), belief (inferred), preference (user stated), tenet (system rule).
epistemic_statusactive, superseded, contradicted, retracted. Tracks belief lifecycle.
domainCategory: settings, workflow, personal, technical, etc.
subject_idWho this belief is about — typically a user_id.
Beliefs support versioning. When a belief is updated, the old version is marked as superseded and a new version is created. You can trace the full evolution chain via the audit timeline.
Context
Context is the output of the memory pipeline — a synthesized packet of relevant beliefs and episode summaries that you inject into your agent's system prompt. When you call POST /v1/context or client.search(), Memgraph performs:
- Vector search across beliefs using your query embedding
- Confidence filtering to exclude low-confidence or stale beliefs
- Episode matching for relevant conversation summaries
- Formatting into a prompt-ready text block
Cognitive Dreaming
Cognitive Dreaming is Memgraph's background consolidation process — inspired by how human brains consolidate memories during sleep. A background worker periodically:
- Picks up episodes with
consolidation_status = pending - Uses an LLM to analyze the episode and extract beliefs
- Creates or updates beliefs (upsert by subject_id + key)
- Generates vector embeddings for semantic search
- Marks the episode as
consolidated
Dreaming requires an OPENAI_API_KEY environment variable for the LLM calls. You can also trigger dreaming manually via POST /v1/dreaming/trigger.
Documents
Documents are supplementary knowledge you upload into Memgraph — PDFs, text files, or web content. They are chunked, embedded, and included in context retrieval alongside beliefs.
POST /v1/documentsCreate a document from text content.
POST /v1/documents/uploadUpload a file (PDF, TXT, etc.).
POST /v1/documents/linkIngest content from a URL.
Knowledge Graph
Memgraph builds a knowledge graph connecting users, beliefs, episodes, and documents through semantic relationships. The graph endpoint (GET /v1/graph) returns nodes and edges for visualization in the Memory Map dashboard.