Skip to main content
A Memory Architecture Configuration (MACA) is the per-instance configuration that controls how memory behaves for your agent. It governs:
  • What is extracted — which categories of structured knowledge Synap captures from conversations.
  • How it is scoped and stored — how memories are partitioned across users, customers, and clients.
  • How it is retrieved — which retrieval strategy is enabled and how results are ranked.
  • How long it is retained — retention and compaction policy for long-running agents.
You do not write a MACA by hand. Instead, you describe your agent in a short use-case file, and Synap generates an optimized MACA tailored to that agent. The use-case file is the contract you author and depend on; the MACA is an internal artifact Synap produces from it.

​
How MACA works

A MACA is generated per instance. When you create an instance you provide a use-case file describing what your agent does and who it serves. Synap analyzes that description and produces a configuration tuned to the agent’s domain and audience — selecting sensible defaults for memory extraction, scoping, retrieval, and retention. Once active, the MACA governs every memory ingested into the instance and every context fetch:
1

You describe the agent

You upload a use-case file — a short Markdown document describing what your agent does, who its users are, what tasks it handles, and any sensitivity or compliance constraints.
2

Synap generates the MACA

Synap analyzes the use-case file and produces an optimized MACA for that agent, choosing defaults for memory extraction, scoping, retrieval, retention, and ranking based on the agent’s domain and audience.
3

The instance runs on it

Every memory ingested into the instance and every context fetch is governed by the active MACA. You can view the current configuration in the Synap Dashboard under your instance’s settings.
4

It evolves with your use case

Re-upload the use-case file whenever your agent’s purpose materially changes — new task categories, new compliance requirements, or a new audience. Synap re-evaluates and regenerates the MACA, and the previous version is preserved so you can roll back if needed.
The MACA is an internal artifact — its internal structure is subject to change as Synap improves its memory pipeline. The stable contract you depend on is the use-case file and the SDK surface, not the raw configuration. You never need to read or edit a MACA directly.
Memory configuration is a deep optimization problem: the right scope partitioning, ranking weights, retrieval strategy, and retention policy all depend on what kind of agent you’re building and what kind of conversations it has. Hand-tuning every knob is the kind of work that delays a launch by weeks. Synap’s job is to handle that. Your job is to describe the agent.

​
The use-case file

The use-case file is the primary input Synap uses to generate your MACA. It’s a plain Markdown document you author and upload when you create an instance. The more detail you provide, the better the resulting configuration.
Uploading a use-case file is optional but strongly recommended. Without it, Synap falls back to a generic default configuration that may not match your agent’s actual needs.

​
Getting the template

The easiest way to start is to download the pre-structured template from the Dashboard:
  1. Navigate to Instances and click Create Instance.
  2. Click Download Template next to the Use-Case Markdown field.
  3. Open the downloaded file in any text editor and fill in your details.
  4. Upload the completed file before clicking Create.

​
What you put in it

The template has eight sections — three required and five optional. A concise, accurate file with only the three required sections outperforms a long but vague file with all eight.
SectionRequiredWhat it tells Synap
Agent ObjectiveYesWhat your agent does and the problem it solves.
Target UsersYesWho interacts with the agent — roles, technical level, usage patterns. Informs scoping granularity.
Task ExamplesYes3–5 representative tasks with a real user message and the expected agent action. The highest-impact section.
Behavioral GuidelinesOptionalExplicit do’s and don’ts that shape how memories are filtered and weighted.
Role DescriptionsOptionalWho the Client, Customer, and User are — maps to Synap’s memory scope hierarchy.
Compliance & Data SensitivityOptionalRegulatory constraints, PII handling, and retention requirements.
Memory PrioritiesOptionalWhat to prioritize, deprioritize, or disable remembering.
Additional ContextOptionalDeployment details, integrations, or any other relevant constraints.
Here is what the required sections look like in practice: 
## Agent Objective

Our agent is a customer support assistant for a B2B SaaS platform.
It helps users troubleshoot integration errors, understand billing,
and navigate the product. The goal is to resolve issues without
escalating to a human agent whenever possible.

## Target Users

Technical leads and developers at mid-market companies (50–500 employees).
Users are generally technical but not deeply familiar with our internal systems.
Most sessions are one-off troubleshooting requests, but power users return
frequently and expect the agent to remember their stack and past issues.

## Task Examples

- **User**: "My webhooks stopped firing after I rotated my API key yesterday."
  **Agent**: Identifies the API key rotation as the likely cause, walks through
  re-registering the webhook endpoint, and stores the user's webhook configuration
  for future reference.

- **User**: "We're migrating from v1 to v2 of your API. What do we need to change?"
  **Agent**: Provides the migration guide and remembers the user is mid-migration
  so future sessions can pick up where they left off.
The optional sections refine the result. For example, Role Descriptions maps directly to Synap’s scope hierarchy — and if your Client, Customer, and User are the same person (as in a personal, B2C-style agent), say so explicitly and Synap will collapse the scope hierarchy accordingly. Note that the Customer scope is a B2B concept; B2C agents typically collapse it away. 
## Role Descriptions

- **Client** (you): Acme SaaS Inc — we build and operate the platform
- **Customer**: Companies that have purchased an Acme subscription (each has their own workspace)
- **User**: An individual employee at a customer company — the person chatting with the agent
Naming compliance constraints explicitly also helps — “GDPR” or “HIPAA” is enough, and Synap maps known frameworks to the appropriate memory-handling rules automatically.

​
How Synap turns it into a MACA

When you upload the file, Synap reads it and generates a MACA tuned to your agent. Concrete Task Examples let Synap infer the right signal types to extract; Role Descriptions inform scoping; Compliance and Memory Priorities shape what is persisted and how it is ranked. You are not locked in to the file you uploaded at creation time. To update it:
  1. Navigate to your instance in the Dashboard.
  2. Go to Settings → Use-Case.
  3. Upload a new file and click Save.
Synap re-evaluates the file and regenerates the MACA through the standard approval workflow before it takes effect.
Updating the use-case file does not alter memories that have already been stored. It only changes how future ingestion and retrieval behave under the new MACA.

​
Next steps

Single-Agent Memory

How memory is organized for a single agent instance.

Memory Types

Which categories of structured knowledge Synap extracts.

Context End to End

Follow a memory from ingestion through retrieval into a context fetch.

Retrieval Modes

Fast (vector + graph) versus accurate retrieval, and when to use each.