> ## 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. > ## Agent Instructions > Maximem Synap is a managed memory layer for AI agents: it ingests conversations and documents, extracts structured memory, and returns scoped context to the agent at retrieval time. > The Python and JavaScript/TypeScript SDKs are the supported way to use Synap. Write integration code with SDK calls, not raw HTTP requests. > Start with the Quickstart: https://docs.maximem.ai/getting-started/quickstart.md. Every SDK method is documented in the SDK reference: https://docs.maximem.ai/sdk-reference/overview.md. # Describe your use case > Write the use-case Markdown file that every new instance is created from. Synap generates the instance's memory architecture from it. 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](/concepts/scope-ladder). ## What to put in each section | Section | What to write | What Synap uses it for | | - | - | - | | **Agent Objective** (required) | What the agent does and the problem it solves, in a few sentences. | The agent's job, which frames every other choice. | | **Target Users** (required) | Who talks to the agent, how technical they are, and how often the same person returns. | Who the memory is about, and how often it is needed again. | | **Interaction Pattern** | Voice, text chat, async (email, tickets) or a mix; the time between turns; how long a session runs. | How often a live conversation is written into long-term memory. | | **Task Examples** (required) | Three to five real user messages, each with what the agent does and what it should remember. | Which kinds of information are worth extracting. | | **Behavioral Guidelines** | Do's and don'ts, especially what must never be stored or shared. | What to filter out, and where the boundaries are. | | **Role Descriptions** | One line each for the Client (you), the Customer and the User. | Who is who in your setup. | | **Compliance & Data Sensitivity** | Regulations that apply, the kinds of personal data that appear, and deletion rules. | Guardrails around sensitive data. | | **Memory Priorities** | What to remember first, what matters less, and what not to track at all. | Which kinds of memory to favor or switch off. | | **Additional Context** | What the agent reads, integrations, languages and regions, rough user numbers. | Anything else. The generator reads the whole file. | 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): ```markdown use-case.md theme={null} # Use-Case Description ## Agent Objective Pet care assistant for Acme Pet Care, a chain of veterinary clinics. Pet owners use it in our mobile app to book visits, ask about their pet's medication, and get vaccination reminders. It should never ask an owner to repeat their pet's details. ## Target Users Pet owners, mostly non-technical. Each owner has their own account and may have several pets. Owners come back every few weeks, usually around a visit. ## Interaction Pattern Text chat in the app. Sessions run 5 to 10 minutes, with 20 to 60 seconds between messages. ## Task Examples - **User**: "Can I book Biscuit in for his booster next week?" **Agent**: Recalls that Biscuit is a four-year-old beagle due a booster, books a slot at the owner's usual clinic, and remembers the appointment. - **User**: "Can Luna have her joint tablets with food?" **Agent**: Recalls Luna's current prescription and her chicken allergy, and answers within what the vet prescribed. - **User**: "We moved, so the Riverside clinic is closer now." **Agent**: Updates the owner's preferred clinic and uses it for future bookings. ## Behavioral Guidelines - Remember each pet's species, age, allergies and current medication. - Refer medical questions beyond the prescription to a vet. - Never share one owner's pets or appointments with another owner. - Don't store payment card numbers in memory. ## Role Descriptions - **Client**: Acme Pet Care, which runs the clinics and the app. - **Customer**: The pet owner. Each owner is their own account. - **User**: The pet owner chatting with the assistant. ## Compliance & Data Sensitivity - Owners' names, phone numbers and home addresses appear in chats. - GDPR applies: an owner can ask us to delete everything we hold about them. ## Memory Priorities - **High priority**: pet details, allergies, medication, upcoming appointments - **Medium priority**: past visit reasons, food brand, preferred clinic - **Low priority**: small talk - **Disable**: tracking the owner's mood ``` ## 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](/guides/pii-protection). ## A weak and a strong description A weak objective gives Synap nothing specific to work with: ```markdown Weak theme={null} ## Agent Objective A helpful AI assistant for our customers. It answers questions and remembers useful information about users to give a better experience. ``` 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: ```markdown Strong theme={null} ## Agent Objective Pet care assistant in the Acme Pet Care app. Owners use it to book visits and ask about their pet's medication. It must remember each pet's species, age, allergies and current prescriptions, so an owner never has to repeat them. Owners come back every few weeks. ``` 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](/integrations/ai-coding-agents) 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. > [!WARNING] > > 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 **Dashboard** 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. **CLI** Log in once. The CLI pairs with your browser session, so there is no key to copy: ```bash theme={null} npx @maximem/synap-cli@latest auth login ``` Then create the instance from your file: ```bash theme={null} maximem-synap instances create \ --name "Pet care assistant" \ --relationship b2c \ --from-file ./use-case.md ``` `--name` and `--from-file` are required. `--relationship` takes `b2c`, `b2b`, `internal` or `agent_to_agent`, and is `b2c` when you leave it out, so pass it for any other kind of agent. The CLI reads the file as UTF-8 text and stops before sending anything if the path does not exist or the file is empty. When the instance exists, mint its runtime key with `maximem-synap api-keys create --instance `. See [CLI overview](/cli/overview). 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 ` shows the same status. > [!NOTE] > > 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 [support@maximem.ai](mailto:support@maximem.ai) 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](/getting-started/bootstrap). > [!TIP] > > 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. ## Related pages > **[Memory architecture](/concepts/memory-architecture)** > > What the generated architecture governs. > **[Shaping your MACA](/guides/configuring-memory)** > > Use-case snippets for common kinds of agents. > **[Quickstart](/getting-started/quickstart)** > > Create an instance, then store and read your first memory. > **[Build with an AI coding agent](/integrations/ai-coding-agents)** > > Install the Synap skill for Claude Code, Cursor, Codex and more. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.