Skip to main content
Every instance starts from a use-case file: a short Markdown document that says what your agent does, who uses it, and what it should remember. Synap reads the file once, when you create the instance, and generates the instance’s memory architecture from it: what gets extracted from conversations, how memory is kept apart between people, and what gets recalled. The file is required, and you cannot replace it after the instance exists, so it pays to write it carefully.

​
What Synap looks for

The generator works from two things you give it: this file, and your answer to Who uses this agent? when you create the instance. It does not see your code or the memories you will send later, so anything it should know has to be in the file. It reads the file looking for:
  • What your business is and what the agent does.
  • Who the users are, and how often the same person comes back.
  • The few things the agent must never forget about a user. Synap takes these in your own words.
  • What the agent reads, such as call transcripts or a CRM record.
  • What sensitive data is involved, and any regulations you name.
  • How a conversation moves: voice or text, the time between turns, how long a session runs.
  • Whether answers have to come back fast, and which languages and regions you serve.
  • Who is who: the organization that owns the data, its customers, and the individual users.
Synap ties each choice to a sentence in your file. Where the file says nothing about one of these points, Synap falls back to a default for it. A requirement you do not write down is not designed for, so write each one as its own plain sentence. Your Who uses this agent? choice decides how memory is isolated between people, and the file cannot override it. Describe your users the same way in both places.

​
Start from the template

In the dashboard’s Create Instance dialog, the Download template link next to Use-Case Markdown saves usecase_template.md. It has nine sections, each with a short instruction, and most with an example. The Recommended sections list under the upload area marks three of them as required: Agent Objective, Target Users and Task Examples. Nothing enforces those sections: the dashboard, the CLI and the server only refuse an empty file. Treat the three required sections as the minimum, and fill in the others where you have something specific to say. You can rename, add or remove sections. Keep a section recognizably about your users and one about roles, because Synap also reads those to suggest your scope ladder.

​
What to put in each section

For Interaction Pattern, describe the conversation and let Synap work out the timing; that is what the template recommends. If you need a specific timing, state it in plain words in that section.

​
An example file

A complete file for an invented company, Acme Pet Care, whose app assistant serves pet owners (a B2C agent):
use-case.md

​
What to leave out

  • The template’s own examples and instructions. Replace or delete each one. An example left in place can read as a statement about your agent.
  • Secrets and real personal data. No API keys, passwords, real customer names or real transcripts. Synap stores the file with the instance exactly as written, a language model reads it, and the Synap team can open it when reviewing an architecture. Describe the kind of data (“owners’ phone numbers appear in chats”), not the data itself.
  • Plans and possibilities. Describe what the agent does and reads today. Synap designs around the data sources you name, not the ones the agent might use one day.
  • Configuration. No YAML, thresholds or model names. You describe the agent; Synap picks the settings.
  • Anything that contradicts your Who uses this agent? choice. That choice decides isolation. If the file says users share memory and the choice says otherwise, the choice wins.
  • Sensitive-data rules as instructions. Naming the sensitive data helps the generator, but what happens to each kind of sensitive value is set in the dashboard. See Sensitive data protection.

​
A weak and a strong description

A weak objective gives Synap nothing specific to work with:
Weak
It names no users, nothing in particular to remember, and no pattern of use, so each of those points falls back to a default. A strong one says who, what and how often:
Strong
Each sentence states one thing Synap can act on: the users, the facts that must never be forgotten (in your words), and how often people return.

​
Let a coding agent draft it

With the Synap skill installed, your coding agent knows the use-case format and can draft the file from your codebase. Give it the template you downloaded from the dashboard so the draft follows the same sections, then ask in plain words:
Draft use-case.md for our Synap instance from this repo, following the attached template. Describe who our users are, what the agent must remember about them, and what it must never keep.
Read the draft before you upload it. Code shows what the agent does; it rarely shows who the users are, how often they return, or what your legal obligations are. Fill those in yourself.
Drafting the file needs no API key. Never paste a Synap API key into a coding agent’s chat. Create the instance yourself, then set SYNAP_API_KEY in your own shell or .env file.

​
Create the instance with your file

  1. Open Instances and click New Instance. On an account with no instances yet, the button reads Create Instance.
  2. Enter an Instance Name.
  3. Under Who uses this agent?, pick the option that matches your Target Users: B2C: End consumers, B2B: Business customers, Internal: Your own employees, or Agent-to-Agent: Technical integration.
  4. Drop your file on the Use-Case Markdown area, or click it to browse. The dashboard accepts .md, .markdown and .txt files up to 512 KB.
  5. Click Create Instance.
Under Or create it from your terminal:, the dialog shows the matching CLI command for the values you entered.
The file is saved as part of creating the instance. If Synap cannot save it, no instance is created.

​
What happens next

1

The instance exists right away

Your file is stored on the instance, and Synap starts generating the memory architecture in the background. In the dashboard dialog you can generate the API key while it runs.
2

Synap generates the architecture

The dialog shows Configuring memory architecture with the current stage, such as “Analyzing use case & business context” or “Designing memory architecture”, and then Memory architecture configured successfully.
3

The architecture becomes active

The instance’s page shows a Memory Architecture Setup card with three steps: Config Generation, Awaiting Review and Review Complete. A new architecture is approved as soon as it is written, so the card moves on to “Memory architecture is active and ready.” If it stops at Awaiting Review with “Configuration is pending admin review”, the architecture is waiting for the Synap team to approve it. From the CLI, maximem-synap instances get <instance-id> shows the same status.
Until the architecture is active, the instance runs on Synap’s defaults, so memories you send are processed without the architecture generated from your file. Send real traffic once the card shows it is active.
If generation fails, the Config Generation step shows the error instead. Email [email protected] with the instance ID.

​
Changing it later

The file is fixed once the instance exists. The dashboard and the CLI have no way to replace it: maximem-synap instances update changes the name and metadata and keeps the stored file. The architecture is generated from the file when the instance is created. To build from a changed description:
  1. Edit your file.
  2. Create a new instance from it, as above.
  3. Generate an API key for the new instance, and set your app’s SYNAP_API_KEY and SYNAP_INSTANCE_ID to the new key and instance ID.
Memories stay in the instance they were sent to, and the new instance starts empty. To carry history over, load it into the new instance with Import existing history.
Keep the file in version control next to your agent’s code. It is your record of what the instance was built from, and the starting point for the next one.

Memory architecture

What the generated architecture governs.

Shaping your MACA

Use-case snippets for common kinds of agents.

Quickstart

Create an instance, then store and read your first memory.

Build with an AI coding agent

Install the Synap skill for Claude Code, Cursor, Codex and more.