Users, teams & tokens

All administration happens on the server with the tam-team command. It works whether or not the server is running.

New in 14.6.0 Superadmins can do the same in the web dashboard: Administration → Users, Departments and Access tokens. Everything below still works from the command line.

In the examples, tam-team --root /srv/tam-team is the Python-package form. With Docker Compose, replace it with:

docker compose -f docker-compose.team.yml run --rm team-memory python /app/src/team_memory/cli.py

(the data directory is set by the container, so no --root is needed).

Identifiers and names

• IDs (users and teams): 1–64 letters, digits, _ or -. Use something stable, like a login: alice, bob-k, platform-team. IDs cannot be renamed.
• Names: 1–128 characters, shown as the author of records.

Users

tam-team --root /srv/tam-team user-add alice 'Alice Moreau'
tam-team --root /srv/tam-team user-add bob 'Bob Kim'

Each user automatically gets a personal scope and access to the shared scope.

Teams (departments)

tam-team --root /srv/tam-team team-add platform 'Platform Engineering'
tam-team --root /srv/tam-team team-add support 'Customer Support'

Memberships and roles

tam-team --root /srv/tam-team member alice platform editor
tam-team --root /srv/tam-team member bob platform reader
tam-team --root /srv/tam-team member bob support editor

Role	Can do in that team’s scope
reader	Search, read, export, view history
editor	Everything a reader can, plus save, edit and delete
manager New in 14.6.0	Everything an editor can, plus the department’s people, activity and onboarding in the dashboard

Running member again with another role changes it. Remove someone from a team:

tam-team --root /srv/tam-team member bob platform remove

Membership is checked on every request, so changes apply immediately, including to tokens already handed out.

Organisation roles and sign-in

New in 14.6.0

Besides department roles, each user has one organisation role for the dashboard: member (default), company_viewer (read-only view of every department) or superadmin (full administration). People sign in to the dashboard with a password they set from a one-time invite code.

tam-team --root /srv/tam-team bootstrap-admin alice 'Alice Moreau'   # first superadmin, prints an invite code
tam-team --root /srv/tam-team user-role bob company_viewer          # member | company_viewer | superadmin
tam-team --root /srv/tam-team invite bob                            # new one-time code; also a password reset

Details, including session and lockout settings, are on the dashboard page.

Tokens

Each person gets their own token, per client if you like. The token identifies the author of every record they write.

tam-team --root /srv/tam-team token-create alice --client claude-code --out ./alice-claude-code.token
tam-team --root /srv/tam-team token-create alice --client cursor --out ./alice-cursor.token

• The token is written to a new file with owner-only permissions (0600). The command refuses to overwrite an existing file.
• The server stores only a SHA-256 hash of the token. If a token file is lost, issue a new one.
• --client is a label shown next to the author (for example codex, cursor, claude-code).

With Docker, write the token into the data volume and copy it out:

docker compose -f docker-compose.team.yml run --rm team-memory \
  python /app/src/team_memory/cli.py token-create alice --client codex --out /team-data/alice.token
docker compose -f docker-compose.team.yml cp team-memory:/team-data/alice.token ./alice.token
docker compose -f docker-compose.team.yml exec team-memory rm /team-data/alice.token

compose cp needs the service container to exist (after up -d). The copied file is a credential: restrict it to its owner (chmod 600 alice.token). The last command removes the copy from the data volume.

Handing a token to an employee

Send it through a channel you would trust with a password (a password manager share, not chat or email). The employee saves it to a file only they can read, for example ~/.config/tam/token with chmod 600. Never give one person another person’s token: everything saved with it is attributed to the token’s owner.

Revoking a token

tam-team --root /srv/tam-team token-revoke --file ./alice-cursor.token

Revocation takes the token itself (the command hashes it and marks it revoked). Revoked tokens stop working on the next request.

With token-revoke, revocation needs the token value, because the server keeps only hashes. To revoke without it, use the dashboard or disable the user (below).

New in 14.6.0 In the dashboard, tokens are listed by owner, client and creation date, and can be revoked without the token value: superadmins revoke any token under Administration → Access tokens, and each user can create and revoke their own under Tokens & password. A new token is shown once. Revoking a token also ends any dashboard session opened with it. Disabling a user in Administration → Users stops all of their tokens and ends their sessions.

When someone leaves

New in 14.6.0

Offboard a person without needing their token files:

tam-team --root /srv/tam-team user-disable alice
# Disabled alice: 3 tokens revoked, 1 sessions ended, 0 invites voided.

user-disable revokes every token, ends dashboard sessions, voids unused invite codes, blocks sign-in and refuses new tokens. The dashboard’s Disable button does the same. Records Alice wrote in team and shared memory keep her as author. tam-team user-enable alice lifts the block; her earlier tokens stay revoked, so she needs a new invite or token.

Her personal memory stays on the server until you decide what to do with it:

tam-team --root /srv/tam-team user-export alice --out ./alice-personal.jsonl
tam-team --root /srv/tam-team user-purge alice --confirm alice

• user-export writes a disabled user’s personal records (including replaced and deleted ones), their full history and their onboarding notes as JSONL. The file is created with mode 0600 and never overwritten. It works while the server runs.
• user-purge deletes that personal area and the user’s onboarding notes. It needs the server stopped, asks you to repeat the user ID, and writes an audit event without content. Backups taken earlier still contain the area.

Audit trail

User, team, membership and token changes are recorded with a UTC timestamp in the server’s identity database (admin_events). New in 14.6.0 Each entry also names the acting user (cli for commands run on the server), and superadmins can filter it in the dashboard’s Audit log. Record changes are recorded in each scope’s history, visible through memory_history.