# User Identity & Cross-Platform Memory

This document provides a simple explanation of how the GoClaw system identifies users, recognizes them as the same person across different channels (Discord, MS Teams, Telegram, Facebook), and consolidates their memory records.

## 1. Gateway & Tenant

When you send a message to GoClaw, it first passes through the **Gateway** (the entry point). At this stage, the system verifies which organization and group the message is coming from.
Previously, these were named differently depending on the channel (e.g., `GuildID` for Discord, `TeamID` for MS Teams), but they have now been consolidated into a unified **TenantID**, which a routing binding matches with the key `tenant_id` whatever the channel. What it holds depends on the channel: the guild (server) ID on Discord; on MS Teams, the conversation ID of the group chat or channel (with `;messageid=…` removed), and nothing in a 1:1 chat. Telegram and Facebook set none. See [Multi-Agent Routing](../routing.md).

## 2. Pairing & Unified User

To accurately identify you, the system requires a **Pairing** step.

- **Pairing Challenge:** If you send a message to the bot for the first time, the system will not recognize you and will respond with a verification challenge code (e.g., `ABCD1234`), instructing you to give this code to your administrator to activate your account. This is the default `channels.dm_policy: pairing`. With `allowlist`, an unknown sender is refused and gets no code; with `open`, everyone gets through. Accounts listed in `channels.allow_from` always get through. The App API skips this step: its callers are already authenticated.
- **Unified Identity:** When the admin registers your account using this code, a unique **Unified ID** (e.g., `u_1710408593123456789`: `u_` and the creation time in nanoseconds) is created for you in the pairing store.
- **Linked Accounts:** Multiple channel-specific IDs (e.g., your Discord numerical ID and MS Teams ID) are linked to this single Unified ID. Therefore, whether you write from Discord tomorrow or MS Teams today, the system immediately recognizes you as the same user via your Unified ID.

This identification process is handled by the "AccessGate" layer within the Gateway, which resolves identity before passing the message context to the Agent.

## 3. GoClaw Role

When a user is registered, a specific **GoClawRole** is assigned to them. For example, if you are configured as an "admin" for an organization, you will retain admin permissions whether you interact via Discord or MS Teams.
This is crucial for the bot to determine authorization rules, such as whether a user is allowed to write to the global memory (shared system instructions).

## 4. Cross-Platform Memory

The most significant benefit of this architecture is **Personal Memory** consistency. 

As the agent interacts with you, it saves important facts about you with the `memory_write` tool (`scope: personal`). 
Previously, if you wrote from Discord, the system saved the memory to a file like `memory/user_discord_123.md`. If you wrote from MS Teams the next day, the bot would create a separate file like `memory/user_msteams_abc.md` and treat you as a completely new, unrecognized user.

Now:
- Regardless of the channel, `AccessGate` identifies you and passes your **Unified ID** to the Agent.
- Personal memory is stored as records in the database under your Unified ID (an unpaired user's platform ID). Every agent reads the same records, whichever channel you write from.
- A personal file from older versions, `user_<id>.md` in `~/.goclaw/memory/personal/` (or in an agent's workspace `memory/` folder), is still read, but only while you have no personal records in the database.
- Personal memory is left out of cron, SOP and webhook runs, and those runs cannot write it.
- As a result, even if you switch between different devices or communication apps, the bot retains a consolidated memory of your history and tasks.

## 5. Administrative Tools

Managing these user records is straightforward and can be done in two ways:

1. **Web Dashboard:** Access the application using a web browser (e.g., `http://localhost:8080`) and go to the "Pairing" menu. You will see verification codes for new users. Simply click the "Approve" button to verify their accounts and update their roles.
2. **Command Line (Terminal):** To manage pairing directly from the terminal. The running gateway keeps the pairing files in memory, so a change made here while it runs is not seen until the gateway restarts, and the gateway's next write can drop it. While the gateway runs, approve on the Web UI's Pairing tab or with `POST /api/pairing` (gateway token, body `{"action": "approve", "code": "ABCD1234", "role": "admin"}`).
  - `goclaw pairing list discord` (List registered Discord users)
  - `goclaw pairing pending discord` (View pending authorization codes)
  - `goclaw pairing approve ABCD1234 --role=admin` (Approve a code and assign the admin role)
  - `goclaw pairing link u_123456 discord 9876543210` (Manually link an account from another channel to a Unified ID)
  - `goclaw pairing revoke u_123456` (Revoke authorization for a unified user)
  
With this architecture, the system operates as a personal assistant tailored directly to your context.