Skip to main content
Configuration changes go through an approval workflow to prevent accidental disruption to production Instances. Draft configurations can be validated and dry-run tested before activation.

​
The three pillars

MACA is organized around three pillars, each governing a distinct phase of the memory lifecycle:

Storage

Where and how memories are stored. Controls vector and graph namespaces, embedding models, scoping strategies, and retention policies.

Ingestion

How incoming data is processed. Controls which memory categories are extracted, extraction modes, chunking strategies, confidence thresholds, and PII handling.

Retrieval

How memories are fetched. Controls default retrieval mode, ranking signals and weights, anticipation (predictive pre-fetch), context budgets, and agent hints.

​
Storage

Storage configuration defines where memories live and how they are organized. You choose between vector storage (for semantic similarity search), graph storage (for relational and structured knowledge), or both. Namespaces provide isolation between Instances, and scoping strategies determine how memories are partitioned across users and customers. 
storage:
  vector:
    namespace: "prod-support-bot"
    enabled: true
    embedding:
      model: "text-embedding-3-small"
      dimension: 1536
  graph:
    namespace: "prod-support-bot"
    enabled: true
  scoping:
    strategy: "user"         # user | customer | instance
    isolation_level: "strict" # strict | shared
  retention:
    max_memory_age_days: 365
    compaction_policy: "auto"
At least one storage engine (vector or graph) must be enabled. The scoping strategy controls how memories are partitioned — user isolates memories per user, customer groups users within an organization, and instance shares memories across the entire Instance. The isolation level determines whether scope boundaries are hard (strict) or allow traversal up the scope chain (shared). See Memory Scopes for a deeper explanation of scoping and isolation. Retention policies control the lifecycle of stored memories. The compaction_policy determines what happens when memories exceed max_memory_age_days: auto lets Synap decide, archive moves them to cold storage, and delete removes them permanently.
Changing the embedding model or dimension on an existing Instance requires re-embedding all stored memories. This is a heavyweight operation. Plan embedding model changes carefully and test with a dry run first.
For details on configuring vector and graph storage backends, see Storage Infrastructure.

​
Ingestion

Ingestion configuration controls how incoming documents are processed and what knowledge is extracted. You select which memory categories to extract, tune extraction quality versus speed, configure chunking behavior, and set PII handling policies. 
ingestion:
  categories:
    facts: true
    preferences: true
    episodes: true
    emotions: true
    temporal_events: true
  extraction:
    mode: "balanced"           # fast | balanced | thorough
    confidence_threshold: 0.6  # 0.0 - 1.0
  chunking:
    strategy: "semantic"       # semantic | fixed | sliding_window
    max_chunk_size: 512
    overlap: 64
  pii:
    handling: "redact"         # passthrough | redact | flag
  hints:
    - "This agent handles customer support for a SaaS product"
    - "Users often discuss billing and subscription topics"

​
Memory categories

At least one memory category must be enabled. Disabled categories are skipped during extraction, reducing processing time and storage usage.
CategoryWhat it capturesExample
factsFactual statements about entities, states, and properties”User lives in Portland”, “Company uses AWS”
preferencesLikes, dislikes, and behavioral preferences with strength and direction”User prefers dark mode”, “User dislikes long emails”
episodesEvent memories with significance scores and participants”User led the Q3 product launch”, “Team completed the migration”
emotionsDetected emotional states with intensity”User expressed frustration with billing”, “User was excited about promotion”
temporal_eventsTime-anchored information: dates, deadlines, schedules”Annual review is next Tuesday”, “Subscription renews monthly on the 15th”
The extraction mode balances speed and quality: fast minimizes latency, thorough maximizes extraction quality, and balanced is the recommended default. The confidence threshold sets the minimum score (0.0—1.0) for an extracted memory to be stored — lower values capture more but with lower quality.
Agent hints are one of the most effective ways to improve extraction quality. Tell Synap what your agent does, what topics users discuss, and what domain-specific terminology to expect. The extraction pipeline uses these hints to better understand ambiguous content.

​
Retrieval

Retrieval configuration controls how memories are fetched and ranked when your agent requests context. You configure retrieval modes, ranking signal weights, anticipation (predictive pre-fetching), and context budgets. 
retrieval:
  default_mode: "accurate"     # fast | accurate
  enabled_modes:
    - "fast"
    - "accurate"
  ranking:
    signals:
      recency: 0.3
      relevance: 0.5
      confidence: 0.2
    weights_sum_validation: true
  anticipation:
    enabled: true
    prefetch_window: 5
  budget:
    max_tokens: 4000
    max_results: 20
  hints:
    - "Prioritize recent interactions over old ones"
    - "User context is more important than general knowledge"
Two retrieval modes are available: fast (~50—100ms, vector-only) and accurate (~200—500ms, vector + graph + ranking). The default_mode is used when no mode is specified per-request. You can disable either mode via enabled_modes to constrain retrieval behavior across your Instance. Ranking signals control how results are ordered. recency favors recent memories, relevance favors semantic similarity, and confidence favors high-confidence extractions. Weights should sum to 1.0 when weights_sum_validation is enabled (the default). Anticipation enables predictive pre-fetching: Synap predicts likely follow-up queries and pre-caches results, reducing latency for conversational flows. The prefetch_window controls how many anticipated queries are pre-cached. Budget settings cap the size of retrieved context. Synap truncates or prioritizes results to stay within the max_tokens limit, ensuring your agent’s context window is used efficiently. See Context Compaction for more on managing token budgets.
Ranking signal weights should sum to 1.0. If weights_sum_validation is true (default), Synap will reject configurations where weights don’t sum to 1.0. Set to false for auto-normalization.

​
Configuration versioning and approval

Every MACA change creates a new version. Configurations progress through a structured approval workflow before becoming active.
Configuration approval workflow: Draft, Pending Review, Approved or Rejected, Active
1

Draft

A new configuration is submitted and saved as a draft. Drafts can be edited freely without affecting the running Instance. Use this stage to iterate on configuration changes.
2

Pending Review

When a draft is ready, it is submitted for review. Synap validates the configuration schema and business rules (e.g., at least one category enabled, weights sum to 1.0, valid embedding dimensions).
3

Approved / Rejected

An administrator approves or rejects the configuration. Rejected configurations include a reason and can be revised and resubmitted. Approved configurations are queued for activation.
4

Active

Once approved, the configuration is applied to the Instance. The previous active configuration is preserved for rollback. All subsequent ingestion and retrieval operations use the new configuration.

​
Apply modes

When submitting a configuration change, you can specify the apply mode:
ModeBehaviorUse case
standardFull validation + schema checks + approval workflowNormal production changes
dry_runValidation only, no changes persistedTesting configuration before committing
forceSkip approval workflow, apply immediatelyEmergency changes (admin-only, audit-logged)

​
Rollback

You can rollback to any previous configuration version. Rollback creates a new version that re-applies the selected historical configuration, maintaining a complete audit trail. 
# Rollback to a previous configuration version
await sdk.config.rollback(
    instance_id="inst_7b2e9a1c3d4f5678",
    target_version=3
)

​
Full configuration example

Here is a complete MACA configuration showing all three pillars side by side for production and development environments: 
# Memory Architecture Configuration — Production
# Instance: inst_7b2e9a1c3d4f5678
# Version: 5

storage:
  vector:
    namespace: "prod-support-bot"
    enabled: true
    embedding:
      model: "text-embedding-3-small"
      dimension: 1536
  graph:
    namespace: "prod-support-bot"
    enabled: true
  scoping:
    strategy: "user"
    isolation_level: "strict"
  retention:
    max_memory_age_days: 365
    compaction_policy: "auto"

ingestion:
  categories:
    facts: true
    preferences: true
    episodes: true
    emotions: true
    temporal_events: true
  extraction:
    mode: "balanced"
    confidence_threshold: 0.6
  chunking:
    strategy: "semantic"
    max_chunk_size: 512
    overlap: 64
  pii:
    handling: "redact"
  hints:
    - "Customer support agent for a B2B SaaS platform"
    - "Users discuss billing, feature requests, and technical issues"

retrieval:
  default_mode: "accurate"
  enabled_modes:
    - "fast"
    - "accurate"
  ranking:
    signals:
      recency: 0.3
      relevance: 0.5
      confidence: 0.2
  anticipation:
    enabled: true
    prefetch_window: 5
  budget:
    max_tokens: 4000
    max_results: 20
  hints:
    - "Prioritize recent support interactions"
    - "Customer account details are high priority"

​
Managing configuration

# Get the active configuration for an instance
config = await sdk.config.get_active(
    instance_id="inst_7b2e9a1c3d4f5678"
)

# Submit a new configuration (enters Draft state)
new_config = await sdk.config.create(
    instance_id="inst_7b2e9a1c3d4f5678",
    config_yaml=open("maca.yaml").read()
)

# Dry run to validate without applying
validation = await sdk.config.apply(
    instance_id="inst_7b2e9a1c3d4f5678",
    version=new_config.version,
    mode="dry_run"
)
print(f"Valid: {validation.is_valid}")
print(f"Warnings: {validation.warnings}")

​
Next steps

Memory Scopes

Learn how scoping strategies control memory isolation.

Storage Infrastructure

Understand vector and graph storage setup in detail.

Configuring Memory Guide

Step-by-step guide to configuring MACA for your use case.

Context Compaction

Manage token budgets with intelligent context compression.