# Template 05 — Memory Architecture Design Template (4 Use Cases) By default, every Managed Agents session is ephemeral: when the session ends, everything the agent learned or produced is gone. Memory stores change this. A memory store is a collection of text documents that persists across sessions. When you attach one to a session, the agent automatically reads relevant memories before starting work and writes new learnings when it finishes — no extra prompting required. This template gives you four patterns for organizing memory stores and entries, with concrete naming conventions you can use immediately. Each pattern matches a different business scenario. Read all four before deciding which to use — many real agents combine two patterns. **Key limits to keep in mind:** - Maximum 8 memory stores per session - Each individual memory entry is capped at 100 KB (~25K tokens) - Structure memory as many small, focused files — not a few large ones - The `prompt` field on a memory store resource (set at session creation) is capped at 4,096 characters --- ## How to Use This Template 1. Read the four patterns and pick the one(s) that match your use case. 2. Fill in the `[FILL IN: ...]` placeholders in the store creation and session attachment code. 3. Use the entry naming conventions as-is or adapt them — consistency matters more than which convention you choose. 4. Populate initial memories via the API (using `memory_stores.memories.write`) before the first session. --- ## Pattern A — Personal Assistant with Per-User Preferences **Use this when:** One agent serves multiple individual users. Each user should have their own memory — User A's preferences must not bleed into User B's session. **Core idea:** One memory store per user. Create the store at user onboarding and attach it to every session for that user. ### Store naming convention ``` store name: "[FILL IN: app-name]-user-[user_id]" Examples: "draftr-user-u001" "draftr-user-u002" ``` ### Store creation (run once per user) ```python store = client.beta.memory_stores.create( name="[FILL IN: app-name]-user-[FILL IN: user_id]", description="Preferences and context for user [FILL IN: user_id].", ) print(store.id) # memstore_01Hx... — save this per-user ``` ### Memory entry naming conventions Use a hierarchical path structure inside the store. Think of each path as a file in a folder. ``` /preferences/ — How this user likes things done tone.md — Communication tone preference output_format.md — Preferred output format (Markdown, JSON, prose) language.md — Language / locale preferences /context/ — Who this user is role.md — Their job title and company current_projects.md — Active projects the agent should be aware of /history/ — Things the agent learned from past sessions corrections.md — Mistakes the user corrected; don't repeat them shortcuts.md — Abbreviations or jargon this user uses ``` ### Seeding initial memories (run after store creation) ```python client.beta.memory_stores.memories.write( memory_store_id=store.id, path="/preferences/tone.md", content="[FILL IN: e.g., 'User prefers concise, direct responses. Avoid filler phrases like \"certainly\" or \"of course.\"']", ) client.beta.memory_stores.memories.write( memory_store_id=store.id, path="/context/role.md", content="[FILL IN: e.g., 'User is a product manager at a 30-person fintech startup.']", ) ``` ### Attaching to a session ```python session = client.beta.sessions.create( agent=agent.id, environment_id=environment.id, resources=[ { "type": "memory_store", "memory_store_id": "[FILL IN: user's store ID]", "access": "read_write", "prompt": "This store contains [FILL IN: user's name]'s preferences and context. Read it before starting any task and update it if you learn something new about their preferences.", } ], ) ``` --- ## Pattern B — Project Tracker with Project-Scoped Memory **Use this when:** Multiple sessions work on the same project over days or weeks. The agent needs to remember the project's current state, decisions made, and work already completed. **Core idea:** One memory store per project. Attach it to every session working on that project. ### Store naming convention ``` store name: "[FILL IN: app-name]-project-[project_id]" Examples: "builder-project-proj-2026-q2-website" "builder-project-proj-acme-integration" ``` ### Store creation (run once per project) ```python store = client.beta.memory_stores.create( name="[FILL IN: app-name]-project-[FILL IN: project_id]", description="State and context for project [FILL IN: project name].", ) ``` ### Memory entry naming conventions ``` /brief/ — What this project is goals.md — Project goals and success criteria constraints.md — Budget, deadline, tech constraints stakeholders.md — Who is involved and their roles /status/ — Current state of the project completed.md — Work that is done (append-only log) in_progress.md — What the agent is currently working on blockers.md — Known blockers or open questions /decisions/ — Choices that should not be revisited architecture.md — Technical architecture decisions scope_changes.md — Agreed scope additions or cuts /artifacts/ — References to produced outputs file_index.md — List of files produced and their paths/purposes ``` ### Attaching to a session ```python session = client.beta.sessions.create( agent=agent.id, environment_id=environment.id, resources=[ { "type": "memory_store", "memory_store_id": "[FILL IN: project store ID]", "access": "read_write", "prompt": "This store contains the state of project [FILL IN: project name]. Read /status/completed.md and /status/in_progress.md first to understand where we left off. Update /status/ entries as you make progress.", } ], ) ``` **Tip:** Keep `/status/completed.md` as an append-only log. Never delete entries — add a new dated line instead. This gives you an audit trail of what the agent accomplished across sessions. --- ## Pattern C — Team Knowledge Base Shared Across Sessions **Use this when:** Multiple agents (or many sessions of the same agent) should all read from a shared corpus of organizational knowledge — style guides, standard operating procedures, approved vendor lists, brand voice rules. **Core idea:** One memory store for the whole team or product. Attach it as `read_only` to all sessions. Only update it deliberately via the API or a dedicated "knowledge curator" agent. ### Store naming convention ``` store name: "[FILL IN: org-name]-knowledge-base" Example: "thornwood-knowledge-base" ``` ### Store creation (run once) ```python store = client.beta.memory_stores.create( name="[FILL IN: org-name]-knowledge-base", description="Shared organizational knowledge, style guides, and SOPs.", ) ``` ### Memory entry naming conventions ``` /brand/ — Brand and voice standards voice.md — Tone of voice guidelines terminology.md — Approved and banned terms style_guide.md — Writing style rules /processes/ — Standard operating procedures content_review.md — Content review and approval workflow client_onboarding.md — Steps for onboarding a new client [FILL IN: your SOP].md /reference/ — Facts the agent should know approved_vendors.md — List of approved tools and vendors pricing_model.md — How your pricing works product_catalog.md — Your product or service list ``` ### Attaching to sessions (read-only) ```python session = client.beta.sessions.create( agent=agent.id, environment_id=environment.id, resources=[ { "type": "memory_store", "memory_store_id": "[FILL IN: knowledge base store ID]", "access": "read_only", # <-- critical: prevents agents from modifying the shared knowledge base "prompt": "This is the [FILL IN: org name] team knowledge base. It contains brand guidelines, SOPs, and reference information. Consult it before making decisions about tone, process, or product details.", } ], ) ``` **Why `read_only`?** Agents running production tasks should not modify shared organizational knowledge without a review step. If an agent discovers that a piece of knowledge is outdated, have it report that back in its output — then a human can update the knowledge base via the API. --- ## Pattern D — Customer-Facing Agent with Isolated Per-Customer Memory **Use this when:** Your product has many end-customers, each of whom gets their own agent experience. Customer A must never see or influence Customer B's memory. **Core idea:** One memory store per customer account (not per user — customer is the billing entity). Create the store when the customer account is provisioned. Pass the store's ID in your session creation code based on the authenticated customer. ### Store naming convention ``` store name: "[FILL IN: app-name]-customer-[customer_id]" Examples: "helpbot-customer-cust-00123" "helpbot-customer-cust-00124" ``` ### Store creation (run once per customer account) ```python store = client.beta.memory_stores.create( name="[FILL IN: app-name]-customer-[FILL IN: customer_id]", description="Memory for customer [FILL IN: customer_id]. Contains product context and interaction history.", ) # Save store.id to your customer database alongside customer_id ``` ### Memory entry naming conventions ``` /account/ — Static customer context (set at onboarding) plan.md — Which plan/tier they are on product_usage.md — Which features they actively use integrations.md — Connected third-party tools /preferences/ — How this customer likes the agent to behave response_style.md — Brief vs. detailed, formal vs. casual escalation_contact.md — Who to escalate to for critical issues /history/ — Learned over time by the agent common_issues.md — Recurring problems for this customer resolved_incidents.md — Past incidents (append-only log) feature_requests.md — Things this customer has asked for ``` ### Attaching to a session (customer-triggered) ```python # customer_store_id is looked up from your database using the # authenticated customer's ID before creating the session session = client.beta.sessions.create( agent=agent.id, environment_id=environment.id, resources=[ { "type": "memory_store", "memory_store_id": "[FILL IN: customer_store_id from your DB]", "access": "read_write", "prompt": "This store contains context for this specific customer. Read /account/ and /preferences/ before responding. Log significant interactions to /history/resolved_incidents.md.", } ], ) ``` **Security reminder:** Never pass a hard-coded store ID in customer-facing code. Always look up the store ID from your database using the authenticated customer's identity. This prevents one customer from accidentally accessing another's memory. --- ## Combining Patterns Many real agents use two stores per session. Example: a customer-facing agent that also needs team knowledge: ```python session = client.beta.sessions.create( agent=agent.id, environment_id=environment.id, resources=[ { "type": "memory_store", "memory_store_id": customer_store_id, # Pattern D "access": "read_write", "prompt": "Customer-specific context and history.", }, { "type": "memory_store", "memory_store_id": knowledge_base_store_id, # Pattern C "access": "read_only", "prompt": "Shared organizational knowledge base. Read-only.", }, ], ) ``` This uses 2 of the 8 available stores per session — well within the limit. --- ## Worked Example — Pattern B: Project Tracker *Fictional business: Vela Agency, a 4-person design studio. Creative director Sofia is using a Managed Agent to help build a new client website over three weeks. Each working session picks up where the last one left off.* ### Store creation ```python store = client.beta.memory_stores.create( name="vela-project-harwick-website-2026", description="State and context for the Harwick & Co. website redesign.", ) # Returns: memstore_01Hxq... — saved to Vela's project database ``` ### Seeded entries (day 1) ```python # Brief client.beta.memory_stores.memories.write( memory_store_id=store.id, path="/brief/goals.md", content="Redesign harwickco.com. Goals: modernize visual design, improve mobile UX, " "launch by May 30 2026. Budget: $8,000 agency fee.", ) client.beta.memory_stores.memories.write( memory_store_id=store.id, path="/brief/constraints.md", content="Must stay on Webflow. No custom code beyond Webflow's built-in JS. " "Brand colors: #1A2E4A (navy), #F4A261 (amber).", ) # Status (initial) client.beta.memory_stores.memories.write( memory_store_id=store.id, path="/status/in_progress.md", content="Week 1: Homepage wireframe.", ) client.beta.memory_stores.memories.write( memory_store_id=store.id, path="/status/completed.md", content="2026-04-21: Discovery call completed. Brief finalized.\n", ) ``` ### Session attachment (runs each working session) ```python session = client.beta.sessions.create( agent=agent.id, environment_id=environment.id, resources=[ { "type": "memory_store", "memory_store_id": "memstore_01Hxq...", "access": "read_write", "prompt": "This is the project memory for the Harwick & Co. website. " "Read /status/completed.md and /status/in_progress.md first " "to understand current progress. Update /status/ as you work.", } ], ) ``` After each session, the agent appends completed work to `/status/completed.md` and updates `/status/in_progress.md` — so the next session always starts with accurate context.