Groups
A group is a named set of Istota users with a memory of its own: a family, a work team, a band, a two-person company. It holds facts whose subject is the group rather than one person, such as how the family does holidays, the plumber's name, or a team's deploy conventions. Before groups, every store was either one user's or the whole deployment's, and CHANNEL.md only covered one conversation.
Each group has two stores:
GROUP.md, a prose file at{mount}/Groups/<group_id>/GROUP.md. It loads into each member's prompt as## Group memoryand is readable by a person with no server running.- A key-value store,
group_kv, for machine state: counters, last-run stamps, lists several members append to. It is the per-user KV store with a group in its key instead of a user.
Admins create groups and appoint owners. Owners manage membership and group details. Every member can edit the shared notebook in Groups or ask the bot to remember something for the group. Ownership grants no access to another member's personal memory, files or credentials.
The charter
Every group store is governed by one rule:
Everything in a group store may be said in front of every member of that group, present and future, in any room where the group's material is loaded. Nothing else goes in it.
The "future" clause is the one that is easy to miss. Adding a member exposes the whole existing store to them, including what was written before they joined. There is no per-fact audience; the charter is the mechanism. The corollary is the default: when in doubt, a fact goes in the user's own USER.md.
The charter appears above the notebook editor, in the seeded GROUP.md comment, in the memory skill's classification gate and on this page. Removing the file comment does not remove the editor's explanation.
No automatic writer
Nothing writes to a group store on its own. The nightly sleep cycle extracts into a user's dated memories and the knowledge graph, and into a room's CHANNEL.md; it never writes GROUP.md or group_kv, and it never copies something from USER.md or the knowledge graph into a group. A test holds this. Members can edit the notebook themselves in Groups. When a member tells the bot "remember this for the family" or similar, the bot runs istota-skill memory append --group <id> or istota-skill kv set --group <id>.
Using Groups
Open Groups to see your current memberships. Select a group to open its Memory, Members, Rooms or Briefings view. Memory is the shared notebook, with an editor, a size warning above 32 KiB and recorded changes. Members shows the current roster. Rooms lists the group's own rooms, which every member is in, and the linked rooms you already belong to, each labelled; a link does not grant room access, and a linked room you are not in is not named. Owners create group rooms from this view (see Group rooms). Files opens the group's folder in Files, where Group memory and Group members lead back to these views.
GROUP.md is the curated notebook. Other files and the memories/ directory are shared documents that every member can add, change and delete from Files (see Group files); they are not automatically recalled or turned into notebook facts. group_kv holds structured state. Linking a room leaves its CHANNEL.md in that room. Personal memory and knowledge graph facts stay personal.
Owners can change the display name and kind, add existing enabled users, change roles and remove members. Every addition requires acknowledgement that the new member can read existing group memory and retained briefing editions. The form lists what access it grants, including the group's own rooms and their history. Ordinary linked rooms are not granted. A member may leave, but the last owner must appoint a replacement in the same operation if other members remain. kind is only a display label; owner grants group management authority.
Admins use Admin → Groups, below Users, to create groups, appoint owners, inspect membership history, recover an ownerless group and archive a group. Creation requires at least one enabled owner; the acting admin need not join. Admins outside the group can inspect its metadata and membership but cannot read its notebook through member pages or the file viewer. The management events list shows members' file changes by type, actor and time, without the file names, since those are member content. It holds the newest 500 events and says so when it is full; istota group show keeps the full details. Older groups without owners remain readable and editable by members and are marked “Needs owner” in administration. Migration does not appoint an owner.
Removing a member ends future access: the group views, Files place and file viewer check membership on the next request, and an already-open editor cannot save after removal. Already delivered messages and downloads remain with their recipients. A running task may already hold admitted content or a directory bind; removal does not recall that snapshot.
Membership history keeps departures and rejoins as separate periods. Role changes keep the membership period and record the old and new role. Archiving preserves data and history but removes member access. There is no hard deletion or reuse of an archived id.
Briefings and All users
The Briefings view lists the group’s definitions and retained editions. Current owners manage them through the same editor used in Briefings. Ownership succession needs no briefing transfer, and an admin outside an ordinary group gains no content access. Members can read history and manage their own delivery mutes. Excluded members retain history access, including editions published before they joined; a new member receives future deliveries only.
All users is the built-in group of enabled installation accounts. Membership follows account lifecycle automatically and cannot be edited by hand. Installation admins author its briefings. Its notebook, files and retained editions are shared with current and future users; it cannot be archived. Every user can read its folder in Files, but only admins can change files there from the web, because admin-authored All users briefings can name files in it. Its existence does not enable a mailing or automatically add group memory or its folder to tasks: only a task in a room linked to All users carries them. See Briefings.
Group files
Every current member of a group can work in its folder from Files the way they do in My files: upload files (with the button or by dropping them), create folders, edit text files, and delete files and empty folders. The same limits apply: the upload size cap, no overwrite (a second file with a name already taken is saved with a number), no rename or move, and a folder must be empty before it can be deleted. The Shared files card on the group's page has an Upload button that puts files at the top of the folder. The All users folder is the exception: only admins can change it from the web.
The server decides which places accept changes, re-checking membership on every request. A person who is not a current member, whose membership ended, or whose group was archived gets the same "Place not found." as for a group that does not exist. Room folders, linked folders and shares from other servers stay read-only in Files.
GROUP.md and memories at the top of the folder are the group's layout. Files will not create, edit, delete or replace either of them there, whether or not they exist: the notebook is edited on the Groups page, where the GROUP.md row's Edit links. The same names inside a subfolder are ordinary files and folders.
Two members editing the same text file share one lock and the revision check, so the second save reports a conflict rather than replacing the first. The check also catches a change a task made in the meantime.
Each change made from Files is recorded as a group event with the member, the action and the path: uploaded, created folder, edited or deleted (a deleted folder is recorded as a delete). The Shared files card lists the newest six under Recent changes. Changes a task makes, and changes made directly on the server, do not pass through the web and are not listed. If recording fails, the change still stands. Nothing notifies other members when a file changes.
A deletion is for every member. The confirmation in Files says so. A group briefing that reads a file from the folder fails its gather while that file is missing.
A member who joins is told, in the acknowledgement an owner gives, that the group's files can be added, changed and deleted by every member. Members who joined before this was possible were not told.
Operator CLI
The CLI and web use the same group management service. A typical setup is:
istota group create family --kind family --name "Family" --owner alice
istota group show family
istota group add-member family bob --revision 1 --acknowledge-history
Use the current revision from show for each later change; the example assumes the newly created group is still at revision 1. Stale revisions are refused. Repeat --owner at creation to choose several owners. add-member --role owner can also promote an existing member. Removal or demotion of the last owner can carry --replacement-owner USER for another current member in the same operation. Archive requires --revision N --confirm.
The immutable id uses lowercase letters, digits, ., _ and -, 2 to 64 characters, starting with a letter or digit; none is reserved for room unlinking. Creation seeds Groups/<id>/GROUP.md and an empty memories/ directory after committing membership. If storage setup fails, the group still exists. Restore the workspace and use Retry storage setup in Admin Groups or istota group ensure-storage ID; do not create another group. Membership administration remains available during a storage outage.
The full command list is in the CLI reference.
Where a group's material loads
Each task works out once which groups it may carry, and that one answer decides three things: the ## Group memory block in the prompt, which Groups/<id> directories are bound into the task's sandbox, and which groups kv --group and memory --group will accept.
A group is in that set when the task's user is a current member and everyone who will read the answer is a member too:
- A conversation with the bot alone loads all of the user's groups except All users, which loads only in a room linked to it. That covers a private room, the user's own SMS or WhatsApp conversation, and a task with no conversation at all.
- A room shared with other people loads only the groups whose current members include everyone in the room. A family room where all four members are in the
familygroup loads it; the same room with a friend in it loads nothing. - Nothing loads on a guest's turn, on a turn whose audience included someone outside the room's members, while a guest or another bot is present, or in a room whose members are not recorded. Email threads without a registered room fall in the last case.
- Personal briefings exclude ambient group memory. Group briefings can read an explicitly selected group notebook or file through their authorized source gather; public research receives neither.
This is deliberately stricter than "recall it but do not repeat it". In a room with a non-member, the bot does not have the group's material at all.
Linking a room to a group
A room can be linked to one group. A linked room carries that group's material and no other group's, so a family room whose members also share a book club loads only family. The link narrows the rule above and never widens it: the linked group still loads only on a member's turn, while everyone in the room is a member of it and no guest or other bot is present. When that does not hold, the room loads no group at all rather than falling back to the others.
The room's host sets the link, and only to a group the host belongs to. In a private room that is the room's one member. Use !room group <id> in the room, !room group none to remove it, or !room group to see the current link; on the web, the Group field in the room settings does the same. Linking to a group you are not in, or one that does not exist, gets the same refusal, so the command does not reveal which groups exist. No group can be named none, so !room group none always means unlink.
A link to a group that is later archived, or that the room's members leave, stays on the room and loads nothing until it applies again.
A member's turn in a shared room runs with everything that member can reach, but that reach is their own data and does not widen any of this. Group material follows only the audience rule above.
Group rooms
A group room belongs to the group rather than to the people in it. Its members are the group's current members, nobody else, and they change when the group's membership changes. An owner creates one from the group's Rooms view with a name; Istota suggests "General" for the first. Nothing creates a group room on its own. A group with no owner, an archived group and a group with no members cannot create one. Group rooms are web chat rooms only in this version.
Membership is managed in Groups, not in the room. Chat labels the room "Membership follows" the group and links its people panel to the group's Members view. There is no per-room invite, remove, leave or delete. Hiding a group room only hides it from your room list: you are still a member and still part of its audience. To leave the room, leave the group.
- Joining the group adds the new member to every group room, with its whole history. The acknowledgement an owner gives when adding a member covers that history.
- Leaving or being removed takes the member out of every group room in the same change. Their room handles stop working, the next batch of an open stream stops, a send from an old tab is refused and does not put them back. Their earlier messages stay in the transcript. Their pending tasks in the room are cancelled and a running one is asked to stop; nothing it produces is delivered. Anything they already downloaded stays with them.
- Archiving the group suspends its rooms for everyone. The transcripts are kept, but nobody can read or post. There is no unarchive in this version.
Current owners decide the room's settings: name, model, speech mode and the rest of what a host decides in an ordinary shared room. A room still has one host, who is accountable for its tasks. The host starts as the owner who created it. When the host leaves the group, a remaining owner takes over, the first by membership order, so the room keeps working after its creator is gone. The room's creator is kept as history and gives no lasting rights. If no owner is left, the room has no host until the group has an owner again.
A group room never loads anyone's personal memory (USER.md, personal recall, knowledge graph facts, playbooks), even while the group has one member, because everything said in it is shared with future members. It loads the group's own notebook under the audience rule above, and no other group's. A member's turn still runs with that member's own tools and resources when they ask for them.
A group room cannot be linked to another group, unlinked, opened in Talk, or given a guest or an external surface. Rooms created before group rooms existed are not converted: a linked room keeps its own members and its own host rules.
How the model sees it
GROUP.md arrives in the user half of the prompt between the knowledge graph facts and channel memory, so memory narrows from the user to the group to the room. Each group gets a ### <display name> heading under one ## Group memory section, in id order.
Any member can write a group's store, and any member's task could have been steered by something it read. So group material reaches the model as untrusted content: the file body in the prompt, the output of memory show --group, and every value read with kv get, kv list and kv set-members --group are wrapped in untrusted-content markers. The prompt says to read it as information, not as instructions. Keys, namespace names and heading names come back bare, because the model has to pass them back exactly.
GROUP.md counts towards max_memory_chars but is never cut, like USER.md and CHANNEL.md. It is read with USER.md's read cap, and the daemon logs a group_memory_large warning once a file passes 32 KB. Nothing trims a group file, so watch for that warning: one member's task can grow the file, and every member's prompt carries it.
Writes and their trail
The notebook editor checks the revision it loaded. If another member changes the file, saving reports a conflict rather than merging or replacing their changes. Web saves and host-side memory --group operations use the same resolved notebook path and file lock under {db_path.parent}/locks/group-memory. Text edits to other group files from Files take their lock in the same directory, keyed by each file's own path. This directory is shared by the daemon and web processes and is outside task sandbox mounts; neither a per-user deferred directory nor a service's private temporary directory is a suitable substitute.
A genuinely missing notebook under an available, validated group root can be created. An unavailable root, oversized file, invalid UTF-8, symlink, special file or read failure is refused rather than shown as an empty editable notebook. Save reads again under the lock, so a file that becomes unreadable after opening cannot be replaced. An oversized notebook returns 413, invalid encoding or unsafe files return 422, unavailable storage or read I/O returns 503, and lock timeout returns 423. Refused reads supply no content or replacement revision. Restore storage or repair the file before editing again.
Memory operations record applied and rejected outcomes in the group's reserved _memory_audit namespace with the writer and task. Web edits record source="web", the actor, timestamp and before/after revision hashes. The notebook's Recorded changes view reads this trail newest first; the CLI can read it with istota group kv-list <id> _memory_audit. It is not a complete version history and cannot restore old versions. Direct filesystem edits can bypass it because admitted tasks have writable group directories. If the file saves but recording fails, the save succeeds with audit_recorded=false and the UI warns that recording failed; retrying the edit would risk duplication.
kv --group writes from a sandboxed task are deferred. The scheduler applies them after the task finishes, and only if the task's user is still a member and the group remains in the task's set. Each value records written_by. A group can never be a delivery target: a group or group:<id> entry in an output target or a CRON.md job is dropped with a warning.
Security notes
Groups/<id>/is bound read-write into the sandbox of a task that carries the group. TheGroups/root and every other group's directory are not bound at all.GROUP.mdis read host-side with the same hardening asUSER.mdandCHANNEL.md: a symlinked directory, a symlinked or special file, or an oversized file is refused rather than followed.- Every refusal from
kv --groupandmemory --groupreadsnot a member of group '<id>', whatever the reason, so the skill CLIs cannot be used to learn which groups exist. - Where tasks run unsandboxed (
istota serveon macOS), the group set still decides what loads into the prompt and what the skill CLIs accept, but nothing stops a task's own file tools from reaching other directories under the mount. See security.
Not in this version
- Membership commands in chat and external invitations.
- Renaming, moving or overwriting group files from Files, and notifying members when a file changes.
- An approval queue, or any automatic extraction into a group store.
- A per-fact audience. The charter is the audience.
- Sharing
Groups/<id>/with members' own Nextcloud accounts, so it would appear in their Files app. - Group-scoped knowledge graph facts.
- Group rooms on Talk or WhatsApp, a group room for part of a group, and converting an existing linked room into a group room.