Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.maximem.ai/llms.txt

Use this file to discover all available pages before exploring further.

Every instance has its own independent MACA. Changes to one instance’s configuration never affect another.
MACA configuration editor showing YAML editing with syntax highlighting and a preview panel

​
Initializing configuration

When an instance is first created, it does not have an active memory architecture configuration. You must initialize one before the instance can process ingestion and retrieval requests.
1

Navigate to the instance detail page

Click the instance in the instances list, then find the Memory Architecture section.
2

Click Initialize Memory Architecture

Synap generates a default YAML configuration tailored to general-purpose use. This default includes sensible settings for vector and graph storage, standard extraction categories, and a balanced retrieval strategy.
3

Review the generated configuration

The generated config enters pending status. Review the settings and adjust them to match your use case before proceeding through the approval workflow.
4

Approve and apply

Once you are satisfied with the configuration, approve it and then apply it to make it active. See the Approval Workflow section below.

​
Configuration structure

MACA is organized into three top-level sections: storage, ingestion, and retrieval. Each section controls a distinct aspect of how the instance handles memory. 
storage:
  vector:
    namespace: "my-instance-vectors"
    dimension: 1536
    enabled: true
  graph:
    namespace: "my-instance-graph"
    enabled: true
  scoping:
    primary_scope: "user"
  retention:
    max_memory_age_days: 365

ingestion:
  categories:
    facts: true
    preferences: true
    episodes: true
    emotions: true
    temporal_events: false
  extraction:
    mode: "standard"
  chunking:
    strategy: "semantic"
  confidence_threshold: 0.7

retrieval:
  default_mode: "fast"
  modes:
    fast:
      enabled: true
    accurate:
      enabled: true
  ranking:
    signals:
      recency: 0.3
      relevance: 0.5
      confidence: 0.2
  context_budget:
    max_tokens: 4096

​
Storage section

The storage section defines where and how memories are persisted.
FieldTypeDescription
vector.namespacestringThe namespace for vector storage. Isolates this instance’s vectors from other instances.
vector.dimensionintegerEmbedding dimension. Default is 1536 (OpenAI embeddings). Must match your embedding model.
vector.enabledbooleanWhether vector storage is active. Disabling is a soft flag — existing data is retained.
graph.namespacestringThe namespace for graph storage. Isolates this instance’s graph data.
graph.enabledbooleanWhether graph storage is active. Disabling is a soft flag — existing data is retained.
scoping.primary_scopestringThe default scope for new memories. One of: user, customer, client, world.
retention.max_memory_age_daysintegerHow long memories are retained before eligible for cleanup.
Disabling vector or graph storage uses a soft flag. Existing data is not deleted — it simply becomes inaccessible until the storage engine is re-enabled. This makes it safe to temporarily disable a storage engine for testing or cost management.

​
Ingestion section

The ingestion section controls what gets extracted from raw content and how it is processed.
FieldTypeDescription
categories.factsbooleanExtract factual statements (e.g., “User lives in San Francisco”)
categories.preferencesbooleanExtract user preferences (e.g., “User prefers dark mode”)
categories.episodesbooleanExtract episodic memories (e.g., “User signed up last Tuesday”)
categories.emotionsbooleanExtract emotional signals (e.g., “User was frustrated with billing”)
categories.temporal_eventsbooleanExtract time-specific events
extraction.modestringExtraction strategy: standard or detailed. Detailed mode extracts more granular information at higher token cost.
chunking.strategystringHow content is split before processing: semantic (meaning-based boundaries) or fixed (character-count boundaries).
confidence_thresholdfloatMinimum confidence score (0.0 - 1.0) for extracted memories to be persisted. Lower values capture more but with less certainty.

​
Retrieval section

The retrieval section defines how memories are searched, ranked, and returned when your agent requests context.
FieldTypeDescription
default_modestringThe default retrieval mode: fast (lower latency, vector-only) or accurate (higher latency, vector + graph).
modes.fast.enabledbooleanWhether fast retrieval mode is available.
modes.accurate.enabledbooleanWhether accurate retrieval mode is available.
ranking.signals.recencyfloatWeight given to how recently a memory was stored (0.0 - 1.0).
ranking.signals.relevancefloatWeight given to semantic similarity to the query (0.0 - 1.0).
ranking.signals.confidencefloatWeight given to extraction confidence score (0.0 - 1.0).
context_budget.max_tokensintegerMaximum number of tokens in the returned context window. Controls how much memory context your agent receives.
Ranking signal weights should sum to 1.0 for predictable behavior. If they do not, Synap normalizes them internally, but explicit weighting makes your intent clearer.

​
Version history

Every modification to the MACA creates a new version. Synap never overwrites a previous configuration — all versions are preserved for auditing and rollback.
Configuration version history table showing version numbers, statuses, timestamps, and who made each change
The version history page shows:
  • Version number — Auto-incremented with each change.
  • Status — The current status of that version (pending, approved, rejected, active).
  • Created by — Who submitted the change.
  • Created at — When the version was created.
  • Applied at — When the version was activated (if applicable).
  • Comments — Review notes from the approval process.
You can view the full YAML for any previous version and compare it side-by-side with the current active configuration.

​
Approval workflow

Configuration changes go through an approval workflow before they can be activated. This prevents accidental or untested changes from affecting production instances.
1

Submit a configuration update

Edit the YAML configuration and submit it. The new version enters pending status.
2

Review the changes

Reviewers (Owners and Admins) can examine the diff between the pending version and the current active configuration. The review system highlights potential issues such as disabling a storage engine, lowering confidence thresholds significantly, or changing scope boundaries.
3

Approve or reject

The reviewer approves or rejects the configuration with optional comments explaining the decision.
  • Approved: The configuration is ready to be applied.
  • Rejected: The submitter should revise and resubmit based on the review feedback.
4

Apply the approved configuration

An approved configuration must be explicitly applied to become active. This is a separate step from approval, giving you control over timing — for example, you might approve during business hours but apply during a maintenance window.

​
Configuration statuses

StatusDescription
PendingSubmitted and awaiting review. Not yet active.
ApprovedReviewed and approved. Ready to be applied.
RejectedReviewed and rejected. Must be revised and resubmitted.
ActiveCurrently applied to the instance. Only one version can be active at a time.

​
Applying configuration

When you apply an approved configuration, it becomes the active configuration for the instance. The previously active configuration is deactivated (but preserved in version history).

​
Apply modes

Synap supports three apply modes to give you control over how changes are activated:
Validates the configuration against schema and business rules, then applies it. This is the recommended mode for most changes.If validation fails, the configuration is not applied and you receive detailed error messages.
Validates the configuration and reports what would change, but does not actually apply it. Use this mode to preview the impact of a change before committing.Dry run checks include:
  • Schema validation (field types, required fields, value ranges)
  • Business rule validation (namespace existence, storage engine connectivity)
  • Diff against the current active configuration
Skips conflict checks and applies the configuration directly. This mode is restricted to Admins and Owners and should only be used when you need to override a known conflict.
Force mode bypasses safety checks. Use it only when you understand the implications and have verified the configuration manually.
Always use dry_run mode first in production to validate changes before applying. This catches schema errors, invalid namespaces, and conflicting settings before they affect your running instance.

​
Rollback

You can revert to any previous configuration version at any time. Rollback is non-destructive — it creates a new version with the contents of the target version, rather than deleting intermediate versions.
1

Open version history

Navigate to the instance’s configuration page and click Version History.
2

Select the target version

Find the version you want to revert to. You can preview its full YAML content.
3

Click Rollback

Confirm the rollback. Synap creates a new version (with a new version number) containing the target version’s configuration. This new version still goes through the approval workflow.
Configuration changes do not affect running conversations. New configuration takes effect for new requests only. If an agent is mid-conversation when you apply a new config, that conversation continues with the previous settings until it ends.

​
API routes

MethodRouteDescription
GET/dashboard/configs/{instance_id}Get the current active MACA config
GET/dashboard/configs/{instance_id}/historyGet the version history
POST/instances/{instance_id}/memory-architecture/initInitialize MACA for a new instance
POST/instances/{instance_id}/memory-architecture/updateSubmit a configuration update
POST/instances/{instance_id}/memory-architecture/apply/{config_id}Apply an approved config
POST/instances/{instance_id}/memory-architecture/rollback/{config_id}Rollback to a previous config
POST/instances/{instance_id}/memory-architecture/review/{config_id}Submit a review (approve/reject)
GET/instances/{instance_id}/memory-architecture/configGet the active config
GET/instances/{instance_id}/memory-architecture/versionsList all config versions

​
Next steps

Configuring Memory Guide

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

Core Concepts: Memory Architecture

Deep dive into how storage, ingestion, and retrieval interact.

Monitoring & Analytics

Measure the impact of configuration changes on performance and usage.

SDK Configuration

How the SDK reads and applies memory architecture configuration at runtime.