Memory Architecture (MACA)

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 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.

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.

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.

It stays tied to that file

The use-case file is fixed once the instance exists, and there is no way to replace it. When your agent’s purpose materially changes (new task categories, new compliance requirements, a new audience), write a new file and create a new instance from it. See Changing it later.

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 specific it is, the better the resulting configuration. Describe your use case is the full guide to writing one.

A use-case file is required to create an instance, and it cannot be replaced afterwards, so write it for the agent you are actually building.

Getting the template

The easiest way to start is to download the pre-structured template from the Dashboard:

Navigate to Instances and click Create Instance.
Click Download template next to the Use-Case Markdown field.
Open the downloaded file in any text editor and fill in your details.
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:

## 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. The architecture is generated once, when the instance is created, and the file cannot be replaced afterwards. To build from a changed description, create a new instance from a new file; memories stay in the instance they were sent to. Describe your use case covers the steps, how to write each section, and what the dashboard shows while the architecture is generated and approved.

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 search) versus accurate retrieval, and when to use each.

Start here

Connecting to Synap

The memory model