Skip to main content
Long-term context is what gives your AI agent a “memory that lasts.” Without it, every conversation starts from scratch. With it, your agent knows that Alice prefers concise summaries, that Acme Corp’s fiscal year ends in March, and that the Q2 budget review is due next Tuesday — even if those facts were learned weeks or months ago.

​
How long-term context is built

Every document you ingest into Synap passes through a multi-stage extraction pipeline that transforms raw text into structured, queryable memories. This pipeline runs asynchronously after ingestion and produces memories that are immediately available for retrieval once processing completes.
1

Document ingestion

You submit a document to Synap via the SDK or API, specifying the document_type (e.g., ai-chat-conversation, document), scope identifiers (user_id, customer_id), and the raw content.
2

Entity extraction and resolution

The pipeline identifies entities mentioned in the document — people, organizations, projects, products, locations — and resolves them against the entity registry. This ensures that “Alice,” “Alice Chen,” and “A. Chen” all map to the same canonical entity.
3

Memory extraction

The pipeline extracts structured memories from the document, categorizing each as one of the five memory types: facts, preferences, episodes, emotions, or temporal events. Each memory receives a confidence or strength score and is linked to its source entities and document.
4

Vector and graph storage

Extracted memories are stored in two complementary engines:
  • Vector storage: memories are embedded as vectors (default dimension: 1536) for semantic similarity search
  • Graph storage: entity relationships and structured connections are stored for graph-based queries and traversal
Ingested Document
    ↓
[ Entity Extraction ] → [ Entity Resolution ]
    ↓
[ Memory Extraction ]
    ↓
┌─────────────────────┐
│   Facts              │
│   Preferences        │  → [ Vector Storage ] (semantic search)
│   Episodes           │  → [ Graph Storage ]  (entity relationships)
│   Emotions           │
│   Temporal Events    │
└─────────────────────┘

​
The five memory types

Long-term context is organized into five structured types, each capturing a different dimension of knowledge:
TypePurposeExample
FactsVerifiable statements and knowledge”Acme Corp uses PostgreSQL for all services”
PreferencesBehavioral choices and tendencies”User prefers bullet-point summaries over paragraphs”
EpisodesEvent narratives and past interactions”Discussed the Q2 roadmap in Monday’s standup”
EmotionsDetected emotional states and sentiment”User was frustrated with the onboarding flow”
Temporal EventsTime-anchored information and schedules”Board meeting every first Monday of the month”
For a detailed breakdown of each type, including extraction behavior, scoring, and configuration, see Memory Types.

​
Retrieval: from storage to context

When your agent needs long-term context, it sends a retrieval request to Synap. The retrieval engine performs a multi-step process to find and rank the most relevant memories:

​
Search and ranking

  1. Semantic search: The search query is embedded and compared against stored memory vectors to find semantically similar memories
  2. Scope filtering: Results are filtered to include only memories from applicable scope levels (user, customer, client, world) based on the provided identifiers
  3. Type filtering: If the retrieval request specifies memory types (e.g., only facts and preferences), non-matching types are excluded
  4. Ranking: Remaining candidates are scored using a combination of:
    • Relevance: semantic similarity to the query
    • Recency: when the memory was created or last accessed
    • Confidence: the extraction confidence score of the memory
  5. Budget enforcement: Results are truncated to fit within the configured token budget
# Retrieve long-term context with full control
context = await sdk.user.context.fetch(
    user_id="user_alice",
    customer_id="acme_corp",
    search_query=["project timeline", "Q2 deliverables"],
    types=["facts", "temporal_events"],  # Only these memory types
)

# context.facts might include:
# - "Q2 roadmap includes API v3 launch and dashboard redesign" (confidence: 0.92)
# - "Engineering team has 12 members across 3 squads" (confidence: 0.88)
#
# context.temporal_events might include:
# - "API v3 launch deadline: June 15" (type: deadline)
# - "Sprint reviews every other Friday" (type: recurring)

​
Scoped access

Long-term memories respect scope boundaries. When you retrieve context for a specific user and customer, Synap searches across the full scope chain: 
USER scope     →  Alice's personal memories (highest priority)
CUSTOMER scope →  Acme Corp's shared knowledge
CLIENT scope   →  Your application's product knowledge
WORLD scope    →  Global domain knowledge (lowest priority)
Narrower scopes take priority. If a user-scoped fact contradicts a customer-scoped fact on the same topic, the user-scoped version is preferred. See Memory Scopes for details on priority resolution.

​
Two sub-categories of long-term context

Long-term context is further organized into two sub-categories based on scope:

Organizational Context

Knowledge at the CLIENT scope — your product documentation, feature announcements, and domain knowledge. Visible to all users across all customers. Ingested without user_id or customer_id. Cached with a 30-minute TTL for performance.

Customer Context

Knowledge at the CUSTOMER scope — shared within a specific customer organization. Company policies, team structure, shared projects. Ingested with customer_id but without user_id. Visible to all users in that customer.
These sub-categories are not separate systems — they are simply long-term memories stored at different scope levels. The distinction is useful for understanding the different ingestion and retrieval patterns you will use for each.

​
How long-term memory grows over time

Long-term context is cumulative. Every ingested document adds to the memory store, and memories persist indefinitely (subject to retention policies). Over time, this creates a rich, deep knowledge base for your agent. 
Week 1:   ████ (initial product docs + first conversations)
Week 4:   ████████████ (more conversations, customer docs added)
Week 12:  ████████████████████████ (months of conversations, entity graph maturing)
Week 24:  ████████████████████████████████████████ (rich knowledge base, strong entity links)
As long-term memory grows:
  • Entity resolution improves: more context means better disambiguation and linking
  • Retrieval becomes richer: more candidate memories for any given query
  • Personalization deepens: the agent develops a more nuanced understanding of each user and customer
  • Ranking becomes more important: with more memories to choose from, the relevance/recency/confidence ranking ensures the best memories surface
Long-term memory growth is self-managing. Synap’s retrieval engine scales with memory volume, and the ranking system ensures that only the most relevant memories are returned regardless of how many exist in storage. You do not need to manually prune or curate memories.

​
Configuration

You can control how long-term context is built and retrieved through the Memory Architecture Configuration:
SettingControlsLocation in MACA
Memory typesWhich of the five types are extractedingestion.categories
Extraction hintsGuidance for the extraction pipelineingestion.extraction_hints
Retrieval modeHow memories are searched (semantic, graph, hybrid)retrieval.mode
Ranking weightsBalance of relevance vs recency vs confidenceretrieval.ranking
Token budgetMaximum tokens returned in a context responseretrieval.budget
Retention policyHow long memories are keptstorage.retention

​
Next steps

Organizational Context

Learn how to ingest and retrieve application-wide knowledge at the Client scope.

Customer Context

Learn how to manage shared knowledge within customer organizations.

Memory Types

Deep dive into the five structured memory types and their extraction behavior.

Memory Scopes

Understand scope boundaries and retrieval priority in detail.