> ## 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.
# Memory Architecture (MACA)
> Every Synap instance runs on a Memory Architecture Configuration (MACA): the per-instance memory policy that governs what is extracted, how it is scoped and stored, how it is retrieved, and how long it is retained. You don't hand-author it; you describe your agent in a use-case file and Synap generates it for you.
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:
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.
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.
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.
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.
| Section | Required | What it tells Synap |
| --------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| **Agent Objective** | Yes | What your agent does and the problem it solves. |
| **Target Users** | Yes | Who interacts with the agent: roles, technical level, usage patterns. Informs scoping granularity. |
| **Task Examples** | Yes | 3-5 representative tasks with a real user message and the expected agent action. The highest-impact section. |
| **Behavioral Guidelines** | Optional | Explicit do's and don'ts that shape how memories are filtered and weighted. |
| **Role Descriptions** | Optional | Who the Client, Customer, and User are. Maps to Synap's memory scope hierarchy. |
| **Compliance & Data Sensitivity** | Optional | Regulatory constraints, PII handling, and retention requirements. |
| **Memory Priorities** | Optional | What to prioritize, deprioritize, or disable remembering. |
| **Additional Context** | Optional | Deployment details, integrations, or any other relevant constraints. |
Here is what the required sections look like in practice:
```markdown theme={null}
## 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.
```markdown theme={null}
## 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
How memory is organized for a single agent instance.
Which categories of structured knowledge Synap extracts.
Follow a memory from ingestion through retrieval into a context fetch.
Fast (vector + graph) versus accurate retrieval, and when to use each.