Agents, Conversations, and Workspaces

Agents, Conversations, and Workspaces

One Mutiro agent can work with many people. Each user has their own conversation and a separate workspace for their files and saved memory.

Imagine a tutor creates @study and shares it with Alice and Bob. The tutor is the owner, who manages the agent and supervises its work. Alice and Bob are users. For this guide, granted developers have the same access as the owner.

One agent, separate conversations

A conversation is the ongoing chat between a person and the agent. Alice opens her chat with @study; Bob opens his. Returning tomorrow or opening that chat on another device continues the same conversation.

Suppose Alice has been practising fractions, while Bob has been practising grammar. Both send the same message: “Can we practise what I got wrong?”

  • In Alice's conversation, the agent uses her recent work on fractions.
  • In Bob's conversation, it uses his recent work on grammar.

The agent can give different answers because it works with a different context in each conversation. Context is the information it has in front of it when responding: messages from that chat, saved facts, and material it is using for the task. Alice and Bob have separate conversation contexts. Neither user has access to the other's conversation.

It is still the same agent. The tutor sets up @study once; Alice and Bob each work with it in their own conversation and workspace.

A place for each person's files and memory

The agent also needs somewhere to keep assignments, generated lessons, and facts saved for later. That place is a workspace.

Alice has her own workspace, Bob has his, and the owner has a workspace for managing the agent. A separate Shared area holds material intended for everyone, such as the syllabus.

Each workspace follows the same basic pattern:

  • Downloads/ — files uploaded in that conversation.
  • MEMORY.md — facts saved for future work with that person.
  • AGENTS.md — instructions for working with that person.

The names repeat, but the contents belong to each workspace. Alice's saved facts and instructions are separate from Bob's. Files appear as they are created or used.

Where the files live

Every agent has a root folder. This is the owner's workspace. Inside it, each user has a separate workspace under users/, and shared/ holds material intended for everyone.

The same pattern appears in the owner's workspace and each user's workspace:

Agent root ← owner's workspace │ ├── Downloads/ Owner's uploads ├── MEMORY.md Saved facts for the owner's conversation ├── AGENTS.md Instructions for working with the owner │ ├── shared/ Common material users can read │ └── syllabus.pdf │ └── users/ ├── alice/ ← Alice's workspace │ ├── Downloads/ Alice's uploads │ ├── MEMORY.md Saved facts about work with Alice │ ├── AGENTS.md Instructions for working with Alice │ └── lesson.html A lesson made for Alice │ └── bob/ ← Bob's workspace ├── Downloads/ Bob's uploads ├── MEMORY.md Saved facts about work with Bob └── AGENTS.md Instructions for working with Bob

Conversation examples

These examples follow the owner, Alice, and Bob in the standard hosted setup.

Person Context for this conversation Workspace for this conversation Access
Owner The tutor's planning chat and saved facts. Other students' chats can be retrieved deliberately for supervision. Agent root Can supervise both students' conversations and workspaces.
Alice Alice's fractions practice, messages, and saved facts. Alice cannot access Bob's conversation. users/alice/ Can access her own workspace and shared material. Cannot access Bob's workspace.
Bob Bob's grammar practice, messages, and saved facts. Bob cannot access Alice's conversation. users/bob/ Can access his own workspace and shared material. Cannot access Alice's workspace.

File and folder purposes

Paths below are relative to the agent root.

Path Purpose Who uses it
Agent root The owner's workspace and the parent folder containing the user workspaces. The owner manages the agent here and can inspect user workspaces.
Downloads/ Files uploaded in the owner's conversation. Available for work in the owner workspace.
MEMORY.md Facts saved while working in the owner's conversation. Used when working in the owner's conversation.
AGENTS.md Instructions for work in the owner's conversation, such as preparing teaching reports. Used in the owner workspace.
shared/ Common material, such as the syllabus or exercise templates. The owner maintains it; users can read it under hosted defaults. Files are read when needed, not automatically loaded into every chat.
users/ The parent folder for individual user workspaces. The owner can inspect them; each user has their own workspace view.
users/alice/ Alice's files and saved memory. Used while working with Alice; the owner can supervise this workspace.
users/alice/Downloads/ Assignments and other files Alice uploads. Available in Alice's workspace and to the owner for supervision.
users/alice/MEMORY.md Facts saved about work with Alice, such as her upcoming fractions test. Used when working in Alice's conversation.
users/alice/AGENTS.md Instructions for working with Alice, such as her learning plan. Used in Alice's workspace.
users/alice/lesson.html An example of a lesson generated for Alice. Kept in Alice's workspace; a lesson intended for everyone could instead go in shared/.
users/bob/ Bob's files and saved memory. Used while working with Bob; the owner can supervise this workspace.
users/bob/Downloads/ Assignments and other files Bob uploads. Available in Bob's workspace and to the owner for supervision.
users/bob/MEMORY.md Facts saved about work with Bob, such as grammar topics to practise. Used when working in Bob's conversation.
users/bob/AGENTS.md Instructions for working with Bob, such as his learning plan. Used in Bob's workspace.

When Alice asks for a lesson, the agent saves it in Alice's workspace. When Bob uploads an assignment, it goes into Bob's workspace.

The owner can access both users' workspaces. Alice and Bob see their own workspace and the shared material in the app. Their files are separate from each other's, but visible to the owner for supervision.

The workspace browser groups files into sections rather than showing this entire folder tree. Some files are protected from editing through the app.

Chat history and saved memory

Chat history contains the messages exchanged in a conversation. MEMORY.md contains facts the agent has saved to use again later.

For example, Alice might tell the agent that she is preparing for a fractions test. If the agent saves that fact, it goes into Alice's MEMORY.md. Bob's saved facts go into Bob's MEMORY.md. Work in the owner's chat uses the owner's MEMORY.md.

The agent does not have every old message in front of it on every reply. It may need to look something up in chat history. Saved memory helps it retain useful facts for future work with that person.

Shared material

The shared/ folder is a common library. The tutor can put a syllabus, reference document, or exercise template there for everyone using @study.

Under hosted defaults, the owner can update shared material and users can read it. A personal lesson for Alice belongs in Alice's workspace; a syllabus for all students belongs in shared/.

A shared file becomes available to read. Its contents are not automatically added to every chat, and putting it there does not send anyone a message or make it public on the internet.

Advanced details

The sections below explain instructions, skills, tool access, and runtime details for owners who need them. They describe the built-in Genie engine and standard hosted layout unless stated otherwise.

Instruction and skill files

These files shape how the agent works. Shared instructions can be supplied to a user conversation without giving that user access to edit the source file.

Path Purpose Who uses it
.agent_instructions.md The agent's identity, values, priorities, voice, and style. These instructions apply across conversations.
.genie/ Agent-wide instructions and the skill catalog. Supplies shared capabilities and context across the agent.
.genie/AGENTS.md Shared operational instructions, such as the common lesson procedure. Loaded across conversations. This is different from the owner's root AGENTS.md.
.genie/skills/ Installed skills, such as a procedure for making quizzes. Discovered across the agent; each conversation sees skills supported by its tools and capabilities.

Instructions: what applies to whom

The agent's instructions have different locations because some apply to everyone and others apply to one person's work.

The location of AGENTS.md determines where it applies. Editing Alice's file changes the instructions for working with Alice. Editing .genie/AGENTS.md changes instructions shared across conversations.

An instruction given only in the owner's chat stays in that chat unless it is saved in the appropriate instruction file. For example, to change the lesson procedure for every student, the tutor can ask the agent to update the shared instructions.

Skills: one procedure, available across the agent

A skill is a reusable set of instructions and supporting resources for doing a task. The owner installs skills once for the agent, in .genie/skills/. Mutiro also provides bundled skills.

For example, a quiz skill can be used with both Alice and Bob. It uses Alice's context and files when making her quiz, and Bob's when making his. The skill supplies the procedure; the current conversation supplies the task and personal context.

Skills are global to the agent. A skill is available in a conversation only when its required tools and capabilities are available there. Installing a skill does not grant additional permissions.

Why the owner has more tools

The tutor may ask: “Review Alice's and Bob's recent work and prepare a follow-up for each.” That requires reading more than the tutor's own conversation.

The agent's conversation tools let it list, read, and search conversations available to this agent. These tools require owner access because they can reveal another user's messages. A student using @study does not receive those tools.

The agent must use the tools to retrieve the relevant conversations; it does not automatically know everything said in them. This lets the owner coordinate work across students while each student continues in their own chat.

Other tools also have limits. Memory tools use the current workspace's memory. File tools use the current workspace and any additional allowed folders. Each agent's enabled tools and access settings determine what it can do.

How the engine handles conversations

Genie is the engine doing the work behind the agent. Mutiro creates and reuses a separate engine session for each conversation; these are sometimes called the agent's “selves.” Each uses that conversation's context and assigned workspace. They run as part of the same agent runtime, rather than as separate agent accounts or computers.

Relative file paths

File tools resolve relative paths from the current workspace. In the standard hosted layout:

Conversation . means Downloads/ means Path to shared material
Owner Agent root Owner's uploads shared/
Alice users/alice/ under agent root Alice's uploads ../../shared/
Bob users/bob/ under agent root Bob's uploads ../../shared/

The runtime supplies the workspace and additional allowed paths to the agent. File tools also enforce denied and read-only paths. The workspace browser has its own viewing and editing controls; visibility in the browser does not imply that a file can be edited there.

Directory instructions

The agent-wide .genie/AGENTS.md and the current workspace's AGENTS.md load as session context.

Genie can also discover a directory's AGENTS.md when readFile reads a file in that directory. For example, reading shared/exercises/lesson.md can load shared/exercises/AGENTS.md.

That file supplies instructions when the directory's material is used. It does not supply instructions to every conversation just because it lives in Shared. Use the agent root's .genie/AGENTS.md for instructions that apply across conversations. Do not assume directory discovery recursively applies an instruction file to every descendant directory.

Instruction files do not grant tools or file access.

Skill discovery

Installed skills are discovered from .genie/skills/ at the agent root. Platform-provided skills are materialized under .genie/bundled-skills/. A .genie/skills/ folder created inside a user's workspace is not a separate discoverable skill catalog.

A session sees the skills supported by its available tools and capabilities. The skill's full instructions load when used. Loading a skill does not execute bundled scripts; scripts still require a suitable execution tool.

Custom workspace layouts

Self-hosted owners can configure workspace, user_workspace, and additional allowed directories. The standard user_workspace: "./users/${USERNAME}" gives each user a separate folder. A template using ${CONVERSATION_ID} can assign folders by conversation instead.

File separation follows those configured paths. If a custom layout points multiple conversations at one folder, their files and MEMORY.md will be shared. Keep separate paths where separate files and memory are required.

See Configuration for these settings. Alternative brains can implement different session and context handling; the Genie details here do not automatically apply to them.