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.

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.