Share (Permissions)

Control access to memories with fine-grained permissions for agents, teams, and organizations.

Overview

By default, memory scoping is determined by the permissions policy set on the namespace. The Share operation enables controlled collaboration by granting other agents, users, or teams access to specific permissioned namespaces.

┌─────────────────────────────────────────────────────┐
│  Organization                                       │
│  ┌─────────────────────┐  ┌─────────────────────┐  │
│  │  Group: editors     │  │  Group: viewers     │  │
│  │  ┌───────┐ ┌───────┐│  │  ┌───────┐ ┌───────┐│  │
│  │  │ alice │ │  bob  ││  │  │ carol │ │  dan  ││  │
│  │  └───────┘ └───────┘│  │  └───────┘ └───────┘│  │
│  └─────────────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────┘

Permissions cascade downward: org-level grants apply to all groups and users, group-level grants apply to all users in that group.

The share tool requires the sharing permission, which is scoped to a namespace prefix—you can only grant permissions for keys within your allowed namespace.

Quick Start

Permissions can be managed within the admin dashboard, or dynamically using the share command. You can manage agents (users), and groups permissions with these commands:

# Create a user
ensue share --command '{"command": "create_user", "username": "alice"}'

# Create a group
ensue share --command '{"command": "create_group", "group_name": "editors"}'

# Add a user to the group
ensue share --command '{"command": "add_member", "group_name": "editors", "username": "alice"}'

# Grant read access to the group for keys matching a pattern
ensue share --command '{"command": "grant", "target": {"type": "group", "group_name": "editors"}, "action": "read", "key_pattern": "shared/"}'

Commands

Command Description
create_user / delete_user Manage users
create_group / delete_group Manage groups
add_member / remove_member Manage group membership
grant Grant permission to org/user/group for a key pattern
revoke Revoke a permission by grant ID
list List all grants (optionally filter by target_type/action)

Permission System

Memory is stored as key-value pairs, where keys are string identifiers. Permissions control access to these keys using a combination of scopes, actions, and regex patterns.

Scopes

Scope Description
org Applies to all users in the organization
group Applies to all users in a specific group
user Applies to a specific user only

Actions

Action Description
read Retrieve memory values
create Create new memory keys
update Modify existing memory values
delete Remove memory values
sharing Manage permissions via the share tool (admin-only, cannot be granted via MCP)

Key Regex

Each permission grant includes a regex pattern that matches against memory key names:

Pattern Matches
.* All keys (wildcard)
^public/.* Keys starting with public/
^team/docs/.* Keys under team/docs/
^alice/.* All keys in alice's namespace

Key Patterns

The key_pattern in commands is a namespace prefix that gets converted to a regex. Only alphanumeric characters, _, -, and / are allowed.

Key Pattern Matches
"" (empty) All keys (wildcard)
alice/ alice/docs, alice/notes/todo
team/ team/data, team/config/settings
shared/docs/ shared/docs/readme, shared/docs/guide

Modifying Access

Grant Access

Grant permissions to a user or group:

# Grant read access to a user
ensue share --command '{"command": "grant", "target": {"type": "user", "username": "bob"}, "action": "read", "key_pattern": "project/"}'

# Grant update access to a group
ensue share --command '{"command": "grant", "target": {"type": "group", "group_name": "developers"}, "action": "update", "key_pattern": "code/"}'

# Grant access to entire organization
ensue share --command '{"command": "grant", "target": {"type": "org"}, "action": "read", "key_pattern": "public/"}'

Revoke Access

Remove previously granted access by grant ID:

ensue share --command '{"command": "revoke", "grant_id": "e516c156-1484-44f7-a47d-65176c0aba8b"}'

List Grants

View all grants, optionally filtered:

# List all grants
ensue share --command '{"command": "list"}'

# Filter by target type
ensue share --command '{"command": "list", "target_type": "group"}'

# Filter by action
ensue share --command '{"command": "list", "action": "update"}'

Next Steps