Storage Infrastructure

Storage engines are managed by Synap Cloud. You do not need to provision or manage any infrastructure. Each Instance gets isolated namespaces in both engines, configured automatically during Instance provisioning.

Overview

Diagram showing vector store and graph store working together to feed retrieval results

The two engines serve fundamentally different query patterns:

Vector store: “Find memories that are semantically similar to this query”
Graph store: “Find all memories connected to this entity, topic, or relationship chain”

In practice, the most effective retrieval combines both: the vector store provides fast, relevance-ranked candidates, and the graph store enriches those candidates with connected context that pure similarity search would miss.

Vector store configuration

The vector store converts each extracted memory into a numerical embedding (a high-dimensional vector) and stores it in a searchable index. When your agent queries for context, the query is also converted to an embedding, and the vector store returns the most semantically similar memories.

How it works

Embedding generation

Each extracted memory (fact, preference, episode, emotion, temporal event) is converted into a vector embedding using the configured embedding model. The embedding captures the semantic meaning of the memory in numerical form.

Indexed storage

Embeddings are stored in a namespace-isolated vector index, organized by scope. Each embedding is associated with the full memory metadata (content, type, confidence, source, entities, timestamps).

Similarity search

When a retrieval query arrives, the query text is converted to an embedding using the same model. The vector store computes cosine similarity between the query embedding and all stored embeddings, returning the closest matches ranked by similarity score.

Choosing an embedding model

Model	Dimension	Speed	Quality	Use Case
`text-embedding-3-small`	1536	Fast	Good	Default. Best balance of speed, quality, and cost for most applications.
`text-embedding-3-large`	3072	Slower	Best	When retrieval precision is critical and you can afford higher latency and storage.
`text-embedding-ada-002`	1536	Fast	Good	Legacy model. Compatible with existing embeddings from other systems.

The embedding dimension must match the model. Using text-embedding-3-small with dimension 3072 (or vice versa) will cause an error during configuration validation. The default configuration uses text-embedding-3-small with dimension 1536.

Vector store characteristics

Characteristic	Detail
Search type	Semantic similarity (cosine distance)
Typical latency	~50ms for a query returning 10-20 results
Namespace isolation	Each Instance has its own vector namespace
Scope filtering	Queries are filtered by scope at the index level (no post-filtering overhead)
Used in	Both `fast` and `accurate` retrieval modes
Best for	Finding content that is semantically related to a query, even when exact terms do not match

When vector search excels

Vector search is particularly effective when:

The query uses different words than the stored memory (“cost savings” matches “reduced expenses by 30%”)
You need fast results with low latency
The user asks broad, open-ended questions
You want to find topically related memories across different conversations

Graph store configuration

The graph store persists entity relationships and structured connections between memories. Rather than treating each memory as an independent document (as the vector store does), the graph store models the web of relationships: who is connected to whom, which facts are about which entities, and how topics and events are linked.

How it works

Entity and relationship extraction

During ingestion, the pipeline extracts not just entities but the relationships between them. “John Smith manages the engineering team at Acme Corp” produces three entities (John Smith, engineering team, Acme Corp) and two relationships (manages, part of).

Graph construction

Entities become nodes and relationships become edges in the Instance’s graph. Each node and edge carries metadata: type, scope, confidence, source, and timestamps. The graph grows organically as new content is ingested.

Relationship traversal

When a retrieval query targets a specific entity or topic, the graph store traverses connected nodes to find related memories. A query about “John Smith” might traverse to “engineering team”, then to “microservices migration”, surfacing memories that pure semantic search would not find.

Graph store characteristics

Characteristic	Detail
Search type	Relationship traversal (graph walk)
Typical latency	~200ms for a query with 2-3 hops of traversal
Namespace isolation	Each Instance has its own graph namespace
Scope filtering	Relationships are scope-aware; traversal respects scope boundaries
Used in	`accurate` retrieval mode only
Best for	Finding connected context, understanding relationships, building entity-centric views

When graph search excels

Graph search is particularly effective when:

You need to understand the relationships around a specific entity (“Tell me everything about Project Atlas”)
Multiple related pieces of information are spread across different conversations
The user asks about connections (“Who is involved in the Q4 planning?”)
You want to build a comprehensive picture from fragmented mentions

Comparing the engines

Feature	Vector Store	Graph Store
Search type	Semantic similarity	Relationship traversal
Speed	Fast (~50ms)	Moderate (~200ms)
Best for	Finding similar content	Finding connected content
Used in	Fast + Accurate modes	Accurate mode only
Handles ambiguity	Well (semantic matching)	Moderate (needs entity resolution)
Discovers indirect connections	No	Yes (multi-hop traversal)
Storage overhead	Moderate (one embedding per memory)	Higher (nodes + edges + metadata)
Scales with	Number of memories	Number of relationships

How both engines feed retrieval

The two engines work together during retrieval, especially in accurate mode:

Diagram showing vector store and graph store results merging into ranked retrieval output

Fast mode

In fast retrieval mode, only the vector store is queried. This provides sub-100ms response times with semantically relevant results. Use this when latency is critical and you do not need deep relationship context.

Query -> Vector Store -> Rank by similarity -> Return results

Accurate mode

In accurate retrieval mode, both engines are queried and their results are merged:

Query -> Vector Store -> Candidates (semantic similarity)
      -> Graph Store  -> Candidates (relationship traversal)
      -> Merge & Deduplicate
      -> Cross-engine ranking (recency + relevance + confidence)
      -> Return results

The cross-engine ranking applies the weights configured in your MACA retrieval configuration. Memories that appear in both engines’ results receive a boost, as convergent evidence from two different search strategies is a strong signal of relevance.

MACA configuration

Both engines are configured through the Memory Architecture Configuration (MACA):

storage:
  vector:
    namespace: "prod-my-agent"
    enabled: true
    embedding:
      model: "text-embedding-3-small"
      dimension: 1536
  graph:
    namespace: "prod-my-agent"
    enabled: true

Enabling and disabling engines

Both engines are enabled by default. You can disable either one, but at least one must remain enabled.

Configuration	Behavior	Trade-off
Both enabled (default)	Full semantic search + relationship traversal	Best retrieval quality, higher storage usage
Vector only	Semantic search only, no relationship context	Lower latency, no graph traversal overhead
Graph only	Relationship traversal only, no semantic similarity	Only useful for highly structured, entity-centric use cases

For most use cases, keep both engines enabled. The vector store handles speed, the graph store handles depth. The additional storage cost is minimal compared to the retrieval quality improvement.

Namespace isolation

Each engine uses a namespace to isolate data between Instances. By default, the namespace is the Instance ID. You can customize namespaces in MACA, which is useful when:

Multiple Instances need to share a storage namespace (rare, for advanced multi-instance setups)
You want human-readable namespace names for operational clarity
You are migrating from a previous Instance and want to reuse the existing namespace

Sharing namespaces between Instances breaks memory isolation. Only do this if you explicitly want Instances to share the same memory store. In most cases, use the default (one namespace per Instance).

Retention and storage lifecycle

Memories stored in both engines follow a lifecycle governed by the retention policy in your MACA configuration:

Stage	Description
Active	Memory is stored, indexed, and available for retrieval. This is the default state for all newly ingested memories.
Stale	Memory exceeds `max_memory_age_days` but has not been evicted yet. Still retrievable but deprioritized in ranking.
Archived	Memory moved to cold storage (if `compaction_policy: archive`). Not immediately retrievable but can be restored.
Evicted	Memory permanently removed (if `compaction_policy: delete`). Irreversible.

storage:
  retention:
    max_memory_age_days: 365     # Memories older than this are candidates for eviction
    compaction_policy: "auto"    # auto | archive | delete

The auto compaction policy lets Synap decide based on memory access patterns. Frequently accessed old memories are retained longer. Rarely accessed memories are archived or evicted sooner. This is the recommended default for most applications.

Monitoring storage

You can monitor storage usage and health through the Dashboard or SDK:

Dashboard
SDK

Navigate to Instances > select your Instance > Storage in the Synap Dashboard. The storage dashboard shows:

Total memories stored in each engine
Storage size and growth trends
Query latency percentiles (p50, p95, p99)
Namespace utilization
Retention policy status (how many memories are stale, archived, or evicted)

# Get storage metrics for an instance
metrics = await sdk.instances.storage_metrics(
    instance_id="inst_7b2e9a1c3d4f5678"
)

print(f"Vector store memories: {metrics.vector.total_memories}")
print(f"Graph store nodes: {metrics.graph.total_nodes}")
print(f"Graph store edges: {metrics.graph.total_edges}")
print(f"Vector query p95 latency: {metrics.vector.query_latency_p95_ms}ms")
print(f"Graph query p95 latency: {metrics.graph.query_latency_p95_ms}ms")

Next steps

Customized Memory Architectures

Configure storage engines, embedding models, and retention policies in MACA.

Memories & Context

Understand how memories flow from ingestion through storage to retrieval.

Entity Resolution

Learn how entities power the graph store’s relationship model.

Context Compaction

Compress context to reduce token costs and optimize retrieval budgets.

Getting Started

Concepts

Setup & Integration

SDK

Dashboard

Connectors

Migration

Guides

Resources

Overview

Vector store configuration

How it works

Choosing an embedding model

Vector store characteristics

When vector search excels

Graph store configuration

How it works

Graph store characteristics

When graph search excels

Comparing the engines

How both engines feed retrieval

Fast mode

Accurate mode

MACA configuration

Enabling and disabling engines

Namespace isolation

Retention and storage lifecycle

Monitoring storage

Next steps

Customized Memory Architectures

Memories & Context

Entity Resolution

Context Compaction

Getting Started

Concepts

Setup & Integration

SDK

Dashboard

Connectors

Migration

Guides

Resources

​Overview

​Vector store configuration

​How it works

​Choosing an embedding model

​Vector store characteristics

​When vector search excels

​Graph store configuration

​How it works

​Graph store characteristics

​When graph search excels

​Comparing the engines

​How both engines feed retrieval

​Fast mode

​Accurate mode

​MACA configuration

​Enabling and disabling engines

​Namespace isolation

​Retention and storage lifecycle

​Monitoring storage

​Next steps

Customized Memory Architectures

Memories & Context

Entity Resolution

Context Compaction

Overview

Vector store configuration

How it works

Choosing an embedding model

Vector store characteristics

When vector search excels

Graph store configuration

How it works

Graph store characteristics

When graph search excels

Comparing the engines

How both engines feed retrieval

Fast mode

Accurate mode

MACA configuration

Enabling and disabling engines

Namespace isolation

Retention and storage lifecycle

Monitoring storage

Next steps