Shaping Your MACA

You do not write MACA YAML. Synap generates and maintains the Memory Architecture for your Instance from the Use-Case Markdown file you upload at Instance creation. This page is a high-level tour of what MACA decides for you, and how to nudge those decisions through your use-case file.

What MACA decides for you

The Memory Architecture is Synap’s internal configuration for one Instance. It determines, for every memory operation against that Instance:

Memory categories

Which categories Synap extracts and stores from your documents and conversations: facts, preferences, episodes, emotions, temporal. Some agents need all of them; others only need facts.

Retrieval behavior

How much context Synap surfaces per query, how aggressive recency weighting is, and how the fast and accurate retrieval modes prioritize different signals.

Scoping

Which scope level (USER, CUSTOMER, or CLIENT) is the primary access pattern for your agent. Synap optimizes indexing and caching around the primary scope, but all four scopes (USER → CUSTOMER → CLIENT → WORLD) are always available.

Retention

How long different categories of memory live before being pruned or compacted, and which signals trigger archival.

You shape all of these by describing your agent in the use-case file. Synap reads the file, infers what your agent actually needs, and generates a MACA tuned for it.

The authoring surface: Use-Case Markdown

The Use-Case Markdown file is a small Markdown document that describes:

What your agent does
Who its users are (consumer, B2B, internal team, etc.)
What kinds of information it needs to remember
Any compliance or retention constraints

Synap uses it to generate your MACA. If your agent’s behavior, audience, or compliance requirements change, re-upload the file. Synap regenerates the MACA from the new version. Existing memories keep their original scope assignment; new memories follow the updated behavior.

Treat the use-case file like a product brief, not a config file. The clearer you are about who the agent serves and what it needs to remember, the better MACA you get.

Snippet recipes

The four patterns below are common shapes. Pick the one closest to your agent and adapt the wording. These are Use-Case Markdown snippets, not configuration files. Drop them into your use-case.md and Synap handles the rest.

B2B customer support

A SaaS support assistant serving multiple customer organizations. Each end-user belongs to a customer, and most knowledge is customer-scoped (their account, their tickets, their team).

# Agent: Acme Support Assistant

## Purpose
An in-product assistant that helps customer-organization users resolve
support issues, look up account details, and reference past tickets.

## Audience
B2B: each end-user belongs to a customer organization. Memory must be
isolated per customer; users within the same customer can share account
and ticket context.

## What it remembers
- Customer account configuration, plan tier, integrations enabled
- Past support tickets and their resolutions
- User-level preferences (preferred contact channel, language)

## Compliance
- 90-day retention on conversation transcripts
- Customer data must never cross customer boundaries

Personal assistant

A consumer-facing personal AI. Single user per Instance ID; deep personalization matters more than throughput.

# Agent: Personal Companion

## Purpose
A personal assistant that helps one user manage their schedule, notes,
relationships, and recurring goals.

## Audience
Consumer: one user per account. No customer/organization concept.

## What it remembers
- User preferences (communication style, tone, dietary needs)
- Episodes (events the user describes in conversation)
- Emotional context (what the user cares about, what frustrates them)
- Temporal references (deadlines, recurring commitments)

## Compliance
- User can request full export and deletion at any time
- No retention limit by default

Knowledge base

A documentation-grounded assistant. Most memory is shared application-wide; per-user state is minimal.

# Agent: Docs Assistant

## Purpose
Answer product and API questions from our ingested documentation, code
samples, and changelog. Users do not "teach" the agent; they query it.

## Audience
All users of the application share the same knowledge surface. No
per-customer isolation needed.

## What it remembers
- Product documentation, API reference, code samples (ingested in bulk)
- Changelog entries with timestamps
- Almost no user-level memory; every user sees the same answers

## Retrieval
- Precision matters more than latency. Default to accurate mode for
  user-facing queries.

High-volume ingestion

An agent ingesting large volumes of documents (support tickets, logs, transcripts) where throughput and graceful degradation under load matter.

# Agent: Ingestion Pipeline

## Purpose
Continuously ingest support tickets and customer-success transcripts so
they're available for retrieval by downstream agents.

## Audience
B2B: tickets are customer-scoped. Retrieval is performed by other
agents, not directly by humans.

## What it remembers
- Ticket content, resolution, escalation path
- Customer metadata associated with each ticket
- Temporal markers (opened, escalated, resolved)

## Throughput
- Volume is measured in thousands of documents per day per customer
- Ingestion uses batch_create with long-range mode
- Latency-sensitive retrieval is not required; fast mode is sufficient

Inspecting what you got

After your Instance is created (or after you re-upload a use-case file), the Dashboard surfaces the resolved Memory Architecture for review:

The categories Synap will extract
The primary scope it picked
The retrieval defaults it tuned

If anything looks wrong for your agent, edit the use-case file and re-upload. That is the supported authoring loop.

Customers do not directly edit, paste, or version MACA YAML. The use-case file is the source of truth; MACA is a derived artifact.

Use-Case Markdown

The authoring surface: what to put in your use-case.md and how Synap reads it.

Customized Memory Architectures

Deeper conceptual background on what MACA is and what it covers.

Memory Scopes

The canonical USER → CUSTOMER → CLIENT → WORLD scope chain and how isolation works.

Memory Types

Reference for facts, preferences, episodes, emotions, and temporal.

Next steps

Multi-User Memory Scoping

Patterns for isolating per-user, per-customer, and per-client memories in multi-tenant apps.

Production Checklist

Security, performance, and monitoring steps before going live.

Writing a Use-Case Markdown File

Step-by-step authoring guide with the full template.

Migrating from Competitors

Map your existing memory layer (Mem0, Zep, Letta, SuperMemory) onto Synap.

Guides

Patterns

Cookbook

What MACA decides for you

Memory categories

Retrieval behavior

Scoping

Retention

The authoring surface: Use-Case Markdown

Snippet recipes

B2B customer support

Personal assistant

Knowledge base

High-volume ingestion

Inspecting what you got

Use-Case Markdown

Customized Memory Architectures

Memory Scopes

Memory Types

Next steps

Multi-User Memory Scoping

Production Checklist

Writing a Use-Case Markdown File

Migrating from Competitors

​What MACA decides for you

Memory categories

Retrieval behavior

Scoping

Retention

​The authoring surface: Use-Case Markdown

​Snippet recipes

​B2B customer support

​Personal assistant

​Knowledge base

​High-volume ingestion

​Inspecting what you got

​Related concepts

Use-Case Markdown

Customized Memory Architectures

Memory Scopes

Memory Types

​Next steps

Multi-User Memory Scoping

Production Checklist

Writing a Use-Case Markdown File

Migrating from Competitors

What MACA decides for you

The authoring surface: Use-Case Markdown

Snippet recipes

B2B customer support

Personal assistant

Knowledge base

High-volume ingestion

Inspecting what you got

Related concepts

Next steps