Configuration - Maximem Synap

The MACA system manages:

Storage: Vector and graph store namespaces, embedding dimensions, retention policies
Ingestion: Memory categories, extraction rules, chunking strategies, agent hints
Retrieval: Retrieval modes, ranking signals, context budgets, anticipation settings

Initialize Configuration

Initialize the memory architecture for a new instance. This generates a default configuration based on the instance’s agent type and queues it for review.

POST /instances/{instance_id}/memory-architecture/init

Path Parameters

instance_id

string

required

The instance ID to initialize configuration for. Format: inst_<hex16>.

Request Body

client_id

string

required

The client ID that owns this instance. Used for authorization.

triggered_by_user_id

string

required

The user ID of the person initiating the configuration. Used for audit logging.

Response

config_id

string

Unique identifier for the generated configuration version.

status

string

Status of the configuration. Typically pending_review after initialization.

message

string

Human-readable description of the result.

review_flags

array

Array of items flagged for review. Each flag includes a field, reason, and severity (info, warning, critical).

Example

curl -X POST "https://api.synap.maximem.ai/instances/inst_f1e2d3c4b5a69078/memory-architecture/init" \
  -H "Authorization: Bearer synap_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "cli_a1b2c3d4e5f67890",
    "triggered_by_user_id": "user_admin_001"
  }'

Response (201 Created)

{
  "config_id": "maca_cfg_1a2b3c4d",
  "status": "pending_review",
  "message": "Memory architecture initialized with default configuration for agent type 'chatbot'. Review required before activation.",
  "review_flags": [
    {
      "field": "storage.vector.embedding_dimension",
      "reason": "Default embedding dimension (1536) set for OpenAI compatibility. Adjust if using a different embedding provider.",
      "severity": "info"
    },
    {
      "field": "retrieval.context_budget",
      "reason": "Default context budget set to 4096 tokens. Consider increasing for agents with long conversations.",
      "severity": "info"
    }
  ]
}

Update Configuration

Submit an updated configuration for an instance. The update goes through validation and is queued for review.

POST /instances/{instance_id}/memory-architecture/update

Path Parameters

instance_id

string

required

The instance ID to update configuration for.

Request Body

client_id

string

required

The client ID that owns this instance.

triggered_by_user_id

string

required

The user ID making the change.

reason

string

required

A description of why this configuration change is being made. Stored in the audit log and displayed during review.

config

object

required

The full or partial configuration update. See the MACA Configuration Schema for the complete structure.

Response

Same shape as the Initialize Configuration response.

Example

curl -X POST "https://api.synap.maximem.ai/instances/inst_f1e2d3c4b5a69078/memory-architecture/update" \
  -H "Authorization: Bearer synap_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "cli_a1b2c3d4e5f67890",
    "triggered_by_user_id": "user_admin_001",
    "reason": "Increase context budget for longer support conversations",
    "config": {
      "retrieval": {
        "context_budget": 8192,
        "mode": "accurate"
      }
    }
  }'

Response

{
  "config_id": "maca_cfg_5e6f7a8b",
  "status": "pending_review",
  "message": "Configuration update submitted. Review required before activation.",
  "review_flags": [
    {
      "field": "retrieval.context_budget",
      "reason": "Context budget increased from 4096 to 8192 tokens. This will increase LLM token usage.",
      "severity": "warning"
    }
  ]
}

Apply Configuration

Apply an approved configuration version to make it the active configuration for the instance.

POST /instances/{instance_id}/memory-architecture/apply/{config_id}

Path Parameters

instance_id

string

required

The instance ID.

config_id

string

required

The configuration version ID to apply.

Request Body

applied_by

string

required

The user ID applying the configuration.

mode

string

The application mode.

Value	Description
`immediate`	Apply the configuration immediately. Active requests may see mixed behavior during the transition.
`graceful`	Wait for in-flight requests to complete before switching. Default.
`canary`	Apply to a percentage of traffic first, then gradually roll out.

Response

success

boolean

Whether the configuration was applied successfully.

status

string

New status of the configuration. active on success.

message

string

Human-readable result message.

applied_at

string

ISO 8601 timestamp of when the configuration was activated.

rollback_config_id

string

The config ID of the previously active configuration. Use this with the Rollback endpoint if needed.

Example

curl -X POST "https://api.synap.maximem.ai/instances/inst_f1e2d3c4b5a69078/memory-architecture/apply/maca_cfg_5e6f7a8b" \
  -H "Authorization: Bearer synap_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "applied_by": "user_admin_001",
    "mode": "graceful"
  }'

Response

{
  "success": true,
  "status": "active",
  "message": "Configuration maca_cfg_5e6f7a8b is now active. Previous config maca_cfg_1a2b3c4d is available for rollback.",
  "applied_at": "2025-01-15T17:00:00Z",
  "rollback_config_id": "maca_cfg_1a2b3c4d"
}

Only configurations with status approved can be applied. Attempting to apply a pending_review or rejected configuration returns a 409 Conflict with code CONFIG_ALREADY_ACTIVE or CONFIG_CONFLICT.

Rollback Configuration

Roll back to a previous configuration version. This re-applies the specified configuration and deactivates the current one.

POST /instances/{instance_id}/memory-architecture/rollback/{config_id}

Path Parameters

instance_id

string

required

The instance ID.

config_id

string

required

The configuration version ID to roll back to. Typically the rollback_config_id returned from the Apply endpoint.

Request Body

applied_by

string

required

The user ID performing the rollback.

reason

string

Reason for the rollback. Stored in the audit log.

Response

Same shape as the Apply Configuration response.

Example

curl -X POST "https://api.synap.maximem.ai/instances/inst_f1e2d3c4b5a69078/memory-architecture/rollback/maca_cfg_1a2b3c4d" \
  -H "Authorization: Bearer synap_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "applied_by": "user_admin_001",
    "reason": "Increased context budget causing higher than expected costs"
  }'

Response

{
  "success": true,
  "status": "active",
  "message": "Rolled back to configuration maca_cfg_1a2b3c4d. Previous config maca_cfg_5e6f7a8b has been deactivated.",
  "applied_at": "2025-01-15T18:30:00Z",
  "rollback_config_id": "maca_cfg_5e6f7a8b"
}

Rollback re-applies the exact previous configuration. It does not undo storage changes (e.g., memories ingested under the new config are retained). Only the processing rules change going forward.

Review Configuration

Submit a review decision for a pending configuration. Configurations must be reviewed before they can be applied.

POST /instances/{instance_id}/memory-architecture/review/{config_id}

Path Parameters

instance_id

string

required

The instance ID.

config_id

string

required

The configuration version ID to review.

Request Body

decision

string

required

The review decision.

Value	Description
`approve`	Approve the configuration. It can then be applied.
`reject`	Reject the configuration. It cannot be applied without resubmission.
`request_changes`	Request changes. The configuration stays in review with feedback notes.

reviewed_by

string

required

The user ID of the reviewer.

notes

string

Review notes or feedback. Displayed to the configuration author.

conflict_resolutions

object

Resolution decisions for flagged conflicts. Keys are the conflict field paths, values are the chosen resolution.

Response

success

boolean

Whether the review was recorded successfully.

status

string

New status of the configuration after review: approved, rejected, or changes_requested.

Example

curl -X POST "https://api.synap.maximem.ai/instances/inst_f1e2d3c4b5a69078/memory-architecture/review/maca_cfg_5e6f7a8b" \
  -H "Authorization: Bearer synap_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "approve",
    "reviewed_by": "user_lead_002",
    "notes": "Context budget increase looks reasonable for support use case."
  }'

Response

{
  "success": true,
  "status": "approved"
}

Get Active Configuration

Retrieve the currently active configuration for an instance.

GET /instances/{instance_id}/memory-architecture/config

Path Parameters

instance_id

string

required

The instance ID.

Response

Returns the full configuration object as JSON. The configuration is stored internally as YAML but serialized to JSON for the API response.

Example

curl -X GET "https://api.synap.maximem.ai/instances/inst_f1e2d3c4b5a69078/memory-architecture/config" \
  -H "Authorization: Bearer synap_your_key_here"

Response

{
  "config_id": "maca_cfg_1a2b3c4d",
  "version": 1,
  "status": "active",
  "storage": {
    "vector": {
      "namespace": "inst_f1e2d3c4b5a69078_vector",
      "embedding_dimension": 1536,
      "distance_metric": "cosine"
    },
    "graph": {
      "namespace": "inst_f1e2d3c4b5a69078_graph",
      "enabled": true
    },
    "retention": {
      "default_ttl_days": null,
      "max_memories_per_scope": 10000
    }
  },
  "ingestion": {
    "categories": ["fact", "preference", "episode", "emotion", "temporal_event"],
    "extraction": {
      "model": "default",
      "confidence_threshold": 0.7
    },
    "chunking": {
      "strategy": "semantic",
      "max_chunk_size": 512,
      "overlap": 64
    }
  },
  "retrieval": {
    "mode": "balanced",
    "context_budget": 4096,
    "ranking_signals": ["recency", "relevance", "confidence"],
    "anticipation": {
      "enabled": true,
      "lookahead_turns": 3
    }
  },
  "applied_at": "2025-01-10T08:30:00Z",
  "applied_by": "user_admin_001"
}

Get Configuration Version

Retrieve a specific configuration version by its ID.

GET /instances/{instance_id}/memory-architecture/config/{config_id}

Path Parameters

instance_id

string

required

The instance ID.

config_id

string

required

The configuration version ID.

Response

Same shape as Get Active Configuration, but may include non-active statuses (pending_review, approved, rejected, superseded).

List Configuration Versions

Retrieve the version history for an instance’s memory architecture configuration.

GET /instances/{instance_id}/memory-architecture/versions

Path Parameters

instance_id

string

required

The instance ID.

Query Parameters

page

integer

Page number. Defaults to 1.

page_size

integer

Items per page. Defaults to 20, maximum 100.

Response

data

ConfigVersionResponse[]

Array of configuration version summaries.

Show ConfigVersionResponse fields

config_id

string

Configuration version ID.

version

integer

Sequential version number.

status

string

Status: active, pending_review, approved, rejected, changes_requested, superseded.

triggered_by

string

User ID who created this version.

reason

string

Reason for the configuration change.

reviewed_by

string

User ID who reviewed this version. null if not yet reviewed.

created_at

string

ISO 8601 timestamp.

applied_at

string

ISO 8601 timestamp of when this version was applied. null if never applied.

Example

curl -X GET "https://api.synap.maximem.ai/instances/inst_f1e2d3c4b5a69078/memory-architecture/versions" \
  -H "Authorization: Bearer synap_your_key_here"

Response

{
  "data": [
    {
      "config_id": "maca_cfg_5e6f7a8b",
      "version": 2,
      "status": "approved",
      "triggered_by": "user_admin_001",
      "reason": "Increase context budget for longer support conversations",
      "reviewed_by": "user_lead_002",
      "created_at": "2025-01-15T16:30:00Z",
      "applied_at": null
    },
    {
      "config_id": "maca_cfg_1a2b3c4d",
      "version": 1,
      "status": "active",
      "triggered_by": "user_admin_001",
      "reason": "Initial configuration",
      "reviewed_by": "user_admin_001",
      "created_at": "2025-01-10T08:00:00Z",
      "applied_at": "2025-01-10T08:30:00Z"
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 2,
  "total_pages": 1
}

Dashboard Configuration Routes

The Dashboard also exposes simplified configuration endpoints for the web UI.

Get Current Configuration Detail

GET /dashboard/configs/{instance_id}

Returns the active configuration for the instance with additional dashboard-specific metadata (last modifier, change frequency, health status).

Get Configuration History

GET /dashboard/configs/{instance_id}/history

Returns the complete version history with diffs between versions, review comments, and timeline visualization data.

These dashboard routes return the same underlying data as the MACA endpoints but with additional presentation metadata optimized for the dashboard UI.

Configuration Schema

The full MACA configuration schema is organized into three sections:

Storage Configuration

Controls how memories are stored in the vector and graph stores.

Field	Type	Default	Description
`storage.vector.namespace`	string	auto-generated	Vector store namespace
`storage.vector.embedding_dimension`	integer	`1536`	Embedding vector dimension
`storage.vector.distance_metric`	string	`cosine`	Distance metric: `cosine`, `euclidean`, `dot_product`
`storage.graph.namespace`	string	auto-generated	Graph store namespace
`storage.graph.enabled`	boolean	`true`	Enable graph storage for entity relationships
`storage.retention.default_ttl_days`	integer	`null`	Default time-to-live in days. `null` for indefinite.
`storage.retention.max_memories_per_scope`	integer	`10000`	Maximum memories per scope before eviction

Ingestion Configuration

Controls how documents are processed through the ingestion pipeline.

Field	Type	Default	Description
`ingestion.categories`	string[]	all types	Memory categories to extract
`ingestion.extraction.model`	string	`default`	Extraction model to use
`ingestion.extraction.confidence_threshold`	float	`0.7`	Minimum confidence for extracted memories
`ingestion.chunking.strategy`	string	`semantic`	Chunking strategy: `semantic`, `fixed`, `sentence`
`ingestion.chunking.max_chunk_size`	integer	`512`	Maximum chunk size in tokens
`ingestion.chunking.overlap`	integer	`64`	Overlap between chunks in tokens
`ingestion.agent_hints`	object	`{}`	Hints for the extraction model about domain-specific terms

Retrieval Configuration

Controls how memories are retrieved and ranked for context.

Field	Type	Default	Description
`retrieval.mode`	string	`balanced`	Retrieval mode: `fast`, `balanced`, `accurate`
`retrieval.context_budget`	integer	`4096`	Maximum tokens in the context response
`retrieval.ranking_signals`	string[]	`["recency", "relevance", "confidence"]`	Signals used for ranking results
`retrieval.anticipation.enabled`	boolean	`true`	Enable anticipatory retrieval
`retrieval.anticipation.lookahead_turns`	integer	`3`	Number of conversation turns to anticipate
`retrieval.agent_hints`	object	`{}`	Hints for the retrieval model

Getting Started

Concepts

Setup & Integration

SDK

Dashboard

Connectors

Migration

Guides

Resources

​Initialize Configuration

​Path Parameters

​Request Body

​Response

​Example

​Update Configuration

​Path Parameters

​Request Body

​Response

​Example

​Apply Configuration

​Path Parameters

​Request Body

​Response

​Example

​Rollback Configuration

​Path Parameters

​Request Body

​Response

​Example

​Review Configuration

​Path Parameters

​Request Body

​Response

​Example

​Get Active Configuration

​Path Parameters

​Response

​Example

​Get Configuration Version

​Path Parameters

​Response

​List Configuration Versions

​Path Parameters

​Query Parameters

​Response

​Example

​Dashboard Configuration Routes

​Get Current Configuration Detail

​Get Configuration History

​Configuration Schema

Initialize Configuration

Path Parameters

Request Body

Response

Example

Update Configuration

Path Parameters

Request Body

Response

Example

Apply Configuration

Path Parameters

Request Body

Response

Example

Rollback Configuration

Path Parameters

Request Body

Response

Example

Review Configuration

Path Parameters

Request Body

Response

Example

Get Active Configuration

Path Parameters

Response

Example

Get Configuration Version

Path Parameters

Response

List Configuration Versions

Path Parameters

Query Parameters

Response

Example

Dashboard Configuration Routes

Get Current Configuration Detail

Get Configuration History

Configuration Schema