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

# Shaping Your MACA

> Every Synap Instance gets a Memory Architecture (MACA) auto-generated from the Use-Case Markdown file you upload. This page explains what MACA controls and how to shape it through your use-case file, with no YAML to author.

<Info>
  You **do not write MACA YAML**. Synap generates and maintains the Memory Architecture for your Instance from the [Use-Case Markdown](/concepts/memory-architecture#the-use-case-file) 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.
</Info>

## 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:

<CardGroup cols={2}>
  <Card title="Memory categories" icon="tags">
    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.
  </Card>

  <Card title="Retrieval behavior" icon="magnifying-glass">
    How much context Synap surfaces per query, how aggressive recency weighting is, and how the `fast` and `accurate` retrieval modes prioritize different signals.
  </Card>

  <Card title="Scoping" icon="layers">
    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.
  </Card>

  <Card title="Retention" icon="clock">
    How long different categories of memory live before being pruned or compacted, and which signals trigger archival.
  </Card>
</CardGroup>

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](/concepts/memory-architecture#the-use-case-file) 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.

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

***

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

```markdown theme={null}
# 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.

```markdown theme={null}
# 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.

```markdown theme={null}
# 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.

```markdown theme={null}
# 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.

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

***

## Related concepts

<CardGroup cols={2}>
  <Card title="Use-Case Markdown" icon="file-text" href="/concepts/memory-architecture#the-use-case-file">
    The authoring surface: what to put in your `use-case.md` and how Synap reads it.
  </Card>

  <Card title="Customized Memory Architectures" icon="brain" href="/concepts/memory-architecture">
    Deeper conceptual background on what MACA is and what it covers.
  </Card>

  <Card title="Memory Scopes" icon="layers" href="/concepts/memory-scopes">
    The canonical `USER → CUSTOMER → CLIENT → WORLD` scope chain and how isolation works.
  </Card>

  <Card title="Memory Types" icon="tags" href="/concepts/memories-and-context#memory-types">
    Reference for `facts`, `preferences`, `episodes`, `emotions`, and `temporal`.
  </Card>
</CardGroup>

***

## Next steps

<CardGroup cols={2}>
  <Card title="Multi-User Memory Scoping" icon="user-group" href="/guides/multi-user-scoping">
    Patterns for isolating per-user, per-customer, and per-client memories in multi-tenant apps.
  </Card>

  <Card title="Production Checklist" icon="check-square" href="/guides/production-checklist">
    Security, performance, and monitoring steps before going live.
  </Card>

  <Card title="Writing a Use-Case Markdown File" icon="pen" href="/concepts/memory-architecture#the-use-case-file">
    Step-by-step authoring guide with the full template.
  </Card>

  <Card title="Migrating from Competitors" icon="right-left" href="/guides/migrate-from-competitors">
    Map your existing memory layer (Mem0, Zep, Letta, SuperMemory) onto Synap.
  </Card>
</CardGroup>