Connect employees

Each employee needs:

1. The server URL, e.g. https://memory.example.com/mcp/ (with the trailing slash).
2. Their personal token saved to a file only they can read, e.g. ~/.config/tam/token (chmod 600).
3. Python 3 on their machine.

The bridge: works with every client

remote.py is a small stdio-to-HTTPS bridge that uses only the Python standard library. The client starts it like a local MCP server; it forwards each request to the team server with the token.

Get it one of two ways:

• Copy the file src/team_memory/remote.py from the repository to the employee’s machine (for example ~/.config/tam/remote.py). Nothing else is needed.
• Or install the package (pipx install total-agent-memory); it provides the same bridge as the tam-remote command.

The bridge reads two variables:

Variable	Value
TAM_REMOTE_URL	The HTTPS /mcp/ endpoint. Plain http:// is accepted only for 127.0.0.1, localhost or ::1.
TAM_REMOTE_TOKEN_FILE	Absolute path to the token file. It is re-read on every request, so replacing the file rotates the token without restarting anything.
TAM_REMOTE_TIMEOUT	Optional, seconds (default 180).

Redirects are refused so a token is never sent to a different address.

Claude Code, Cursor, Windsurf, Claude Desktop and other mcpServers clients

{
  "mcpServers": {
    "total-agent-memory": {
      "command": "python3",
      "args": ["/Users/alice/.config/tam/remote.py"],
      "env": {
        "TAM_REMOTE_URL": "https://memory.example.com/mcp/",
        "TAM_REMOTE_TOKEN_FILE": "/Users/alice/.config/tam/token"
      }
    }
  }
}

Put this in the client’s MCP config file (Claude Code: ~/.claude.json; Cursor: ~/.cursor/mcp.json; Claude Desktop: claude_desktop_config.json). With the package installed, use "command": "tam-remote" and "args": [] instead.

On Windows, use the full path to python.exe and Windows paths, e.g. "C:\\Users\\alice\\.config\\tam\\remote.py".

Codex CLI

The same values as a TOML table in ~/.codex/config.toml:

[mcp_servers.total-agent-memory]
command = "python3"
args = ["/Users/alice/.config/tam/remote.py"]
env = { TAM_REMOTE_URL = "https://memory.example.com/mcp/", TAM_REMOTE_TOKEN_FILE = "/Users/alice/.config/tam/token" }

Direct HTTP (clients that can send headers)

The /mcp/ endpoint is a standard streamable-HTTP MCP endpoint that accepts Authorization: Bearer <token>. Clients that let you set request headers can connect without the bridge. For example, in Claude Code:

claude mcp add --transport http total-agent-memory https://memory.example.com/mcp/ \
  --header "Authorization: Bearer $(cat ~/.config/tam/token)"

This stores the token in the client’s config file. The bridge avoids that by reading the token file at request time, which is why the repository documents the bridge as the default.

First steps for the employee

Ask them to type in their client:

List my memory scopes.

The agent calls memory_scopes and shows their name, client label and the scopes they can use: personal, each team they belong to (with read or write access) and shared.

Then:

• “Save to the platform team: deploys freeze every Friday after 14:00.” → memory_save with scope: {"kind": "team", "team_id": "platform"}.
• “Save for me only: I’m investigating the flaky checkout test.” → personal is the default.
• “What do we know about the deploy freeze?” → memory_recall across all their scopes; results say which scope each came from.
• “Who changed that record and why?” → memory_history.

If it does not connect

Symptom	Cause
Remote MCP request failed (HTTP 401)	Token file empty, wrong, or token revoked
Tool error forbidden on a save (“Workspace is read-only” / “Workspace unavailable”)	The person is a reader in that team, or not a member
Remote connections require HTTPS	URL is http:// to a non-loopback host
redirects are disabled	URL is missing the trailing / or points at http:// that redirects to https://
(HTTP 429)	The server is at its request limit; retry shortly

The bridge writes one JSON line per failure to the client’s MCP log (stderr), without the token.