Memories & Context - Maximem Synap

Think of memories as the knowledge in a library’s catalog, and context as the specific books and notes a researcher pulls from the shelves for a particular question. Synap manages both the catalog and the act of pulling the right materials.

What is a Memory?

A Memory is a unit of structured knowledge that Synap extracts from raw documents. When you ingest content (whether it is an AI chat conversation, a PDF, a knowledge base article, or a plain text document) Synap’s extraction pipeline breaks it down into discrete, typed memory units. It does not store raw text. Each memory has:

A type: one of five structured categories (fact, preference, episode, emotion, temporal event)
A confidence or strength score: a 0.0 to 1.0 value indicating extraction certainty
Source references: links back to the original document and extraction context
Entity links: connections to resolved entities (people, organizations, concepts)
Scope: the visibility boundary (user, customer, client, or world)
Timestamps: creation time, last accessed time, and optional temporal anchors

This structure (typed, scored, and enriched) is what enables Synap to retrieve precisely relevant information rather than returning large blocks of unprocessed text.

A single ingested document can produce dozens or hundreds of individual memories. A five-minute conversation might yield facts about the user’s preferences, an episode describing what they discussed, temporal events about upcoming deadlines, and emotional context about how they felt.

What is Context?

Context is the assembled output that Synap delivers to your AI agent when it requests information. A context response contains:

Retrieved memories: the most relevant memories from long-term storage, ranked by relevance, recency, and confidence
Conversation history: the accumulated short-term context from the current session (if applicable)
Scope metadata: information about which scope levels contributed to the response

Context is what your agent consumes. When your agent needs to generate a response, it fetches context from Synap and uses the returned memories and history to inform its output. The quality of your agent’s responses depends directly on the quality and relevance of the context Synap provides.

# Fetching context for an agent response
context = await sdk.user.context.fetch(
    user_id="user_alice",
    customer_id="acme_corp",  # B2B: required. B2C: omit, auto-resolved.
    search_query=["project timeline", "upcoming deadlines"]
)

# The returned context exposes one field per memory type:
# context.facts            -> relevant factual memories
# context.preferences      -> user preferences
# context.episodes         -> relevant past interactions
# context.emotions         -> detected emotional states
# context.temporal_events  -> time-anchored information

Short-term vs Long-term Memory

Synap distinguishes between two categories of memory based on their lifespan and purpose.

Short-term Context

The accumulated context from the current conversation session. It builds turn by turn as the user and agent exchange messages. Short-term context lives only for the duration of the conversation and is managed through context compaction to stay within token limits.Characteristics:

Ephemeral: exists only during the active session
Grows with each conversational turn
Subject to compaction when it exceeds configured thresholds
Contains the immediate conversational state, recent decisions, and in-progress topics

Long-term Context

Extracted, structured knowledge that persists across conversations and sessions. Long-term memories are produced by the ingestion pipeline and stored in vector and graph engines. They survive indefinitely (subject to retention policies) and are retrieved based on relevance to the current query.Characteristics:

Persistent: survives across sessions, days, months
Built from ingested documents via the extraction pipeline
Stored in vector and graph storage engines
Retrieved based on semantic relevance, recency, and confidence scoring

The interplay between short-term and long-term memory is central to Synap’s value. During a conversation, your agent draws on both: short-term context provides immediate conversational continuity (“we were just talking about the Q2 budget”), while long-term context provides deep knowledge (“Alice prefers executive summaries” and “Acme Corp’s fiscal year ends in March”).

Memory types

Synap’s extraction pipeline produces five distinct types of structured memory. Each type captures a different dimension of knowledge and maps to a field on the context response.

Type	What it captures	Key metric	Context field	Example
Facts	Verifiable statements and knowledge	Confidence (0.0-1.0)	`facts`	”The API rate limit is 1,000 req/min”
Preferences	Likes, dislikes, and behavioral choices	Strength (0.0-1.0) + direction	`preferences`	”User prefers concise responses”
Episodes	Event narratives and interactions	Significance (0.0-1.0)	`episodes`	”Discussed migration plan in standup”
Emotions	Detected emotional states	Intensity (0.0-1.0)	`emotions`	”User expressed frustration with onboarding”
Temporal Events	Time-anchored information	Event type (point/recurring/deadline)	`temporal_events`	”Board meeting scheduled for March 15”

Facts provide grounding, preferences enable personalization, episodes give narrative continuity, emotions support empathy, and temporal events enable time-awareness.

Terminology. “Confidence”, “extraction confidence”, and “extraction certainty” all refer to the same number on a Fact. Preferences use a parallel concept called strength, Episodes use significance, and Emotions use intensity. Use the field name that matches the memory type you’re inspecting.

Facts

Facts are the backbone of long-term memory. A fact is a verifiable, declarative statement extracted from ingested content: knowledge about people, organizations, products, processes, and the world. Each fact carries a confidence score between 0.0 and 1.0 reflecting how certain the pipeline is that the extracted fact is accurate.

0.9-1.0: Explicitly stated, unambiguous facts (“The company was founded in 2019”)
0.7-0.9: Strongly implied or clearly inferable facts (“The team uses agile methodology”)
0.5-0.7: Moderately confident extractions, may need verification
Below 0.5: Low confidence, typically filtered out at ingest

The same confidence value plays two roles: at ingest it acts as a hard filter (default threshold 0.7), and at retrieval it is returned on every fact (fact.confidence) so your agent can decide whether to trust, qualify, or ignore each one. Higher-confidence facts surface before lower-confidence ones at the same relevance level, and conflicting facts across scopes are resolved by scope priority (user > customer > client > world).

Fact: "Acme Corp's engineering team has 25 members across 4 squads"
Confidence: 0.95
Scope: CUSTOMER
Entities: [Acme Corp, engineering team]

Preferences

Preferences capture likes, dislikes, behavioral tendencies, and personal choices: what enables your agent to personalize its responses. Each has a direction (positive = likes/wants, negative = dislikes/avoids) and a strength (0.0 = mild, 1.0 = very strong). A positive preference for “concise responses” at strength 0.9 tells the agent to keep answers short; a negative preference for “jargon” at strength 0.7 tells it to use plain language.

Preference: "Prefers executive summaries before detailed explanations"
Strength: 0.88
Direction: positive
Scope: USER
Entities: [Alice Chen]

Episodes

Episodes capture event narratives: things that happened, interactions that occurred, activities that took place. They give your agent a sense of history and narrative continuity, answering the question “What happened?” Each carries a significance score (0.0-1.0) indicating how important or impactful the episode is, from major decisions and milestones (0.8+) down to routine mentions. Episodes let the agent reference past decisions (“In our previous meeting, you decided to use PostgreSQL”) and demonstrate continuity in ongoing relationships.

Episode: "Discussed the Q2 roadmap in the Monday standup; decided to prioritize API v3"
Significance: 0.82
Scope: CUSTOMER
Entities: [Q2 roadmap, API v3, Monday standup, engineering team]

Emotions

Emotions capture detected emotional states, sentiment, and affective signals from conversations, enabling your agent to respond with empathy, recognizing when a user is frustrated, excited, anxious, or satisfied. Each carries an intensity score (0.0-1.0) reflecting how strongly the emotion was expressed. Emotional memories let the agent acknowledge feelings, adjust tone, celebrate wins, and approach sensitive topics carefully.

Emotion: "User expressed frustration with the onboarding documentation being outdated"
Intensity: 0.78
Scope: USER
Entities: [Alice Chen, onboarding, documentation]

Emotion extraction is optional. Synap turns it off automatically for use cases where it does not apply (e.g., technical Q&A bots) based on your use-case file.

Temporal events

Temporal events capture time-anchored information (dates, deadlines, recurring schedules, and time-sensitive facts) making your agent time-aware. Each has an event_type:

Point-in-time

A specific, one-time event anchored to a particular date or time, e.g. “Board meeting on March 15, 2026” or “API v3 launched on January 20, 2026”.

Recurring

An event that repeats on a schedule, e.g. “Sprint reviews every other Friday at 2pm” or “Monthly all-hands on the first Monday of each month”.

Deadline

A time-bound constraint or due date, e.g. “Q2 OKRs due by June 30” or “Contract renewal deadline: April 15”.

Temporal events let the agent provide timely reminders, reference schedules, and understand urgency.

Temporal Event: "API v3 migration must be completed by June 30, 2026"
Event type: deadline
Scope: CUSTOMER
Entities: [API v3, migration]

Which types your Instance extracts

Synap decides which of the five types to extract based on your agent’s Use-Case Markdown file. Mention the behavior you need (personalization, continuity, emotional awareness, scheduling) and Synap enables the right categories. Types your agent will never use are skipped to save processing time and storage.

Scenario	Typical types extracted
Technical Q&A bot	Facts
Personal assistant	Facts, Preferences, Episodes, Temporal Events
Support agent	Facts, Preferences, Episodes, Emotions
Full-featured agent	All five

If your agent’s use case changes, re-upload the use-case file and Synap will update the active configuration. See Customized Memory Architectures.

Filtering by type during retrieval

When fetching context, use the types parameter to return only specific memory types:

# Retrieve only facts and preferences
context = await sdk.user.context.fetch(
    user_id="user_alice",
    customer_id="acme_corp",  # B2B: required. B2C: omit, auto-resolved.
    search_query=["project status"],
    types=["facts", "preferences"]
)

# Omit `types` to retrieve all five (default behavior)

How memories become context

The journey from raw data to delivered context follows a well-defined pipeline.

Ingestion

You submit raw content to Synap via the SDK. This can be an AI chat conversation, a document, a knowledge base article, or any text content. You specify the document_type, and optionally the user_id and customer_id to set the scope.

Extraction

Synap’s pipeline processes the raw content through multiple extraction stages. It identifies entities, resolves them against known entities, and extracts structured memories (facts, preferences, episodes, emotions, temporal events) with confidence scores and source references.

Storage

Extracted memories are stored in both vector storage (for semantic similarity search) and graph storage (for entity relationships and structured queries). Memories are indexed by scope, type, entity, and embedding vector.

Retrieval

When your agent needs context, it sends a retrieval request with search queries and scope identifiers. Synap searches across applicable scope levels, finding memories that are semantically relevant to the query.

Context Assembly

Retrieved memories are merged across scopes, deduplicated, ranked by relevance/recency/confidence, and assembled into a structured context response. This response is delivered to your agent, ready to inform its next output.

Raw Document
    ↓
[ Ingestion ] → [ Extraction ] → [ Storage ]
                                      ↓
                              [ Vector + Graph ]
                                      ↓
                   Query → [ Retrieval ] → [ Context Assembly ]
                                                    ↓
                                            Structured Context
                                            → Your AI Agent

Next steps

Context End-to-End

How short-term and long-term context accumulate, compact, and combine across a session.

Retrieval Modes

Fast (vector + graph) versus accurate (adds LLM subquery decomposition + reranking).

Memory Scopes

How memory isolation works across users, customers, and organizations.

How Ingestion Works

The extraction pipeline that turns raw documents into typed memories.

​What is a Memory?

​What is Context?

​Short-term vs Long-term Memory

Short-term Context

Long-term Context

​Memory types

​Facts

​Preferences

​Episodes

​Emotions

​Temporal events

​Which types your Instance extracts

​Filtering by type during retrieval

​How memories become context

​Next steps

Context End-to-End

Retrieval Modes

Memory Scopes

How Ingestion Works

What is a Memory?

What is Context?

Short-term vs Long-term Memory

Memory types

Facts

Preferences

Episodes

Emotions

Temporal events

Which types your Instance extracts

Filtering by type during retrieval

How memories become context

Next steps